@noble/curves 1.7.0 → 1.8.0

package/src/abstract/tower.ts

@@ -1,20 +1,19 @@
+/**
+ * Towered extension fields.
+ * Rather than implementing a massive 12th-degree extension directly, it is more efficient
+ * to build it up from smaller extensions: a tower of extensions.
+ *
+ * For BLS12-381, the Fp12 field is implemented as a quadratic (degree two) extension,
+ * on top of a cubic (degree three) extension, on top of a quadratic extension of Fp.
+ *
+ * For more info: "Pairings for beginners" by Costello, section 7.3.
+ * @module
+ */
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
 import * as mod from './modular.js';
 import { bitLen, bitMask, concatBytes, notImplemented } from './utils.js';
 import type { ProjConstructor, ProjPointType } from './weierstrass.js';
 
-/*
-Towered extension fields
-
-Rather than implementing a massive 12th-degree extension directly, it is more efficient
-to build it up from smaller extensions: a tower of extensions.
-
-For BLS12-381, the Fp12 field is implemented as a quadratic (degree two) extension,
-on top of a cubic (degree three) extension, on top of a quadratic extension of Fp.
-
-For more info: "Pairings for beginners" by Costello, section 7.3.
-*/
-
 // 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);
@@ -75,7 +74,20 @@ function calcFrobeniusCoefficients<T>(
 }
 
 // This works same at least for bls12-381, bn254 and bls12-377
-export function psiFrobenius(Fp: mod.IField<Fp>, Fp2: Fp2Bls, base: Fp2) {
+export function psiFrobenius(
+  Fp: mod.IField<Fp>,
+  Fp2: Fp2Bls,
+  base: Fp2
+): {
+  psi: (x: Fp2, y: Fp2) => [Fp2, Fp2];
+  psi2: (x: Fp2, y: Fp2) => [Fp2, Fp2];
+  G2psi: (c: ProjConstructor<Fp2>, P: ProjPointType<Fp2>) => ProjPointType<Fp2>;
+  G2psi2: (c: ProjConstructor<Fp2>, P: ProjPointType<Fp2>) => ProjPointType<Fp2>;
+  PSI_X: Fp2;
+  PSI_Y: Fp2;
+  PSI2_X: Fp2;
+  PSI2_Y: Fp2;
+} {
   // Ψ endomorphism
   const PSI_X = Fp2.pow(base, (Fp.ORDER - _1n) / _3n); // u^((p-1)/3)
   const PSI_Y = Fp2.pow(base, (Fp.ORDER - _1n) / _2n); // u^((p-1)/2)
@@ -120,7 +132,37 @@ export type Tower12Opts = {
   Fp12finalExponentiate: (num: Fp12) => Fp12;
 };
 
-export function tower12(opts: Tower12Opts) {
+export function tower12(opts: Tower12Opts): {
+  Fp: Readonly<mod.IField<bigint> & Required<Pick<mod.IField<bigint>, 'isOdd'>>>;
+  Fp2: mod.IField<Fp2> & {
+    NONRESIDUE: Fp2;
+    fromBigTuple: (tuple: BigintTuple | bigint[]) => Fp2;
+    reim: (num: Fp2) => { re: bigint; im: bigint };
+    mulByNonresidue: (num: Fp2) => Fp2;
+    mulByB: (num: Fp2) => Fp2;
+    frobeniusMap(num: Fp2, power: number): Fp2;
+  };
+  Fp6: mod.IField<Fp6> & {
+    fromBigSix: (tuple: BigintSix) => Fp6;
+    mulByNonresidue: (num: Fp6) => Fp6;
+    frobeniusMap(num: Fp6, power: number): Fp6;
+    mul1(num: Fp6, b1: Fp2): Fp6;
+    mul01(num: Fp6, b0: Fp2, b1: Fp2): Fp6;
+    mulByFp2(lhs: Fp6, rhs: Fp2): Fp6;
+  };
+  Fp4Square: (a: Fp2, b: Fp2) => { first: Fp2; second: Fp2 };
+  Fp12: mod.IField<Fp12> & {
+    fromBigTwelve: (t: BigintTwelve) => Fp12;
+    frobeniusMap(num: Fp12, power: number): Fp12;
+    mul014(num: Fp12, o0: Fp2, o1: Fp2, o4: Fp2): Fp12;
+    mul034(num: Fp12, o0: Fp2, o3: Fp2, o4: Fp2): Fp12;
+    mulByFp2(lhs: Fp12, rhs: Fp2): Fp12;
+    conjugate(num: Fp12): Fp12;
+    finalExponentiate(num: Fp12): Fp12;
+    _cyclotomicSquare(num: Fp12): Fp12;
+    _cyclotomicExp(num: Fp12, n: bigint): Fp12;
+  };
+} {
   const { ORDER } = opts;
   // Fp
   const Fp = mod.Field(ORDER);
@@ -173,6 +215,7 @@ export function tower12(opts: Tower12Opts) {
   const Fp2Nonresidue = Fp2fromBigTuple(opts.FP2_NONRESIDUE);
   const Fp2: mod.IField<Fp2> & Fp2Utils = {
     ORDER: FP2_ORDER,
+    isLE: Fp.isLE,
     NONRESIDUE: Fp2Nonresidue,
     BITS: bitLen(FP2_ORDER),
     BYTES: Math.ceil(bitLen(FP2_ORDER) / 8),
@@ -339,6 +382,7 @@ export function tower12(opts: Tower12Opts) {
 
   const Fp6: mod.IField<Fp6> & Fp6Utils = {
     ORDER: Fp2.ORDER, // TODO: unused, but need to verify
+    isLE: Fp2.isLE,
     BITS: 3 * Fp2.BITS,
     BYTES: 3 * Fp2.BYTES,
     MASK: bitMask(3 * Fp2.BITS),
@@ -495,6 +539,7 @@ export function tower12(opts: Tower12Opts) {
 
   const Fp12: mod.IField<Fp12> & Fp12Utils = {
     ORDER: Fp2.ORDER, // TODO: unused, but need to verify
+    isLE: Fp6.isLE,
     BITS: 2 * Fp2.BITS,
     BYTES: 2 * Fp2.BYTES,
     MASK: bitMask(2 * Fp2.BITS),

package/src/abstract/utils.ts

@@ -1,4 +1,9 @@
+/**
+ * Hex, bytes and number utilities.
+ * @module
+ */
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
+
 // 100 lines of code in the file are duplicated from noble-hashes (utils).
 // This is OK: `abstract` directory does not use noble-hashes.
 // User may opt-in into using different hashing library. This way, noble-hashes
@@ -155,7 +160,7 @@ export function concatBytes(...arrays: Uint8Array[]): Uint8Array {
 }
 
 // Compares 2 u8a-s in kinda constant time
-export function equalBytes(a: Uint8Array, b: Uint8Array) {
+export function equalBytes(a: Uint8Array, b: Uint8Array): boolean {
   if (a.length !== b.length) return false;
   let diff = 0;
   for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
@@ -177,7 +182,7 @@ export function utf8ToBytes(str: string): Uint8Array {
 // Is positive bigint
 const isPosBig = (n: bigint) => typeof n === 'bigint' && _0n <= n;
 
-export function inRange(n: bigint, min: bigint, max: bigint) {
+export function inRange(n: bigint, min: bigint, max: bigint): boolean {
   return isPosBig(n) && isPosBig(min) && isPosBig(max) && min <= n && n < max;
 }
 
@@ -186,7 +191,7 @@ export function inRange(n: bigint, min: bigint, max: bigint) {
  * @example
  * aInRange('x', x, 1n, 256n); // would assume x is in (1n..255n)
  */
-export function aInRange(title: string, n: bigint, min: bigint, max: bigint) {
+export function aInRange(title: string, n: bigint, min: bigint, max: bigint): void {
   // Why min <= n < max and not a (min < n < max) OR b (min <= n <= max)?
   // consider P=256n, min=0n, max=P
   // - a for min=0 would require -1:          `inRange('x', x, -1n, P)`
@@ -202,7 +207,7 @@ export function aInRange(title: string, n: bigint, min: bigint, max: bigint) {
  * Calculates amount of bits in a bigint.
  * Same as `n.toString(2).length`
  */
-export function bitLen(n: bigint) {
+export function bitLen(n: bigint): number {
   let len;
   for (len = 0; n > _0n; n >>= _1n, len += 1);
   return len;
@@ -213,14 +218,14 @@ export function bitLen(n: bigint) {
  * NOTE: first bit position is 0 (same as arrays)
  * Same as `!!+Array.from(n.toString(2)).reverse()[pos]`
  */
-export function bitGet(n: bigint, pos: number) {
+export function bitGet(n: bigint, pos: number): bigint {
   return (n >> BigInt(pos)) & _1n;
 }
 
 /**
  * Sets single bit at position.
  */
-export function bitSet(n: bigint, pos: number, value: boolean) {
+export function bitSet(n: bigint, pos: number, value: boolean): bigint {
   return n | ((value ? _1n : _0n) << BigInt(pos));
 }
 
@@ -228,7 +233,7 @@ export function bitSet(n: bigint, pos: number, value: boolean) {
  * Calculate mask for N bits. Not using ** operator with bigints because of old engines.
  * Same as BigInt(`0b${Array(i).fill('1').join('')}`)
  */
-export const bitMask = (n: number) => (_2n << BigInt(n - 1)) - _1n;
+export const bitMask = (n: number): bigint => (_2n << BigInt(n - 1)) - _1n;
 
 // DRBG
 
@@ -295,15 +300,15 @@ export function createHmacDrbg<T>(
 // Validating curves and fields
 
 const validatorFns = {
-  bigint: (val: any) => typeof val === 'bigint',
-  function: (val: any) => typeof val === 'function',
-  boolean: (val: any) => typeof val === 'boolean',
-  string: (val: any) => typeof val === 'string',
-  stringOrUint8Array: (val: any) => typeof val === 'string' || isBytes(val),
-  isSafeInteger: (val: any) => Number.isSafeInteger(val),
-  array: (val: any) => Array.isArray(val),
-  field: (val: any, object: any) => (object as any).Fp.isValid(val),
-  hash: (val: any) => typeof val === 'function' && Number.isSafeInteger(val.outputLen),
+  bigint: (val: any): boolean => typeof val === 'bigint',
+  function: (val: any): boolean => typeof val === 'function',
+  boolean: (val: any): boolean => typeof val === 'boolean',
+  string: (val: any): boolean => typeof val === 'string',
+  stringOrUint8Array: (val: any): boolean => typeof val === 'string' || isBytes(val),
+  isSafeInteger: (val: any): boolean => Number.isSafeInteger(val),
+  array: (val: any): boolean => Array.isArray(val),
+  field: (val: any, object: any): any => (object as any).Fp.isValid(val),
+  hash: (val: any): boolean => typeof val === 'function' && Number.isSafeInteger(val.outputLen),
 } as const;
 type Validator = keyof typeof validatorFns;
 type ValMap<T extends Record<string, any>> = { [K in keyof T]?: Validator };
@@ -313,7 +318,7 @@ export function validateObject<T extends Record<string, any>>(
   object: T,
   validators: ValMap<T>,
   optValidators: ValMap<T> = {}
-) {
+): T {
   const checkField = (fieldName: keyof T, type: Validator, isOptional: boolean) => {
     const checkVal = validatorFns[type];
     if (typeof checkVal !== 'function') throw new Error('invalid validator function');
@@ -342,7 +347,7 @@ export function validateObject<T extends Record<string, any>>(
 /**
  * throws not implemented error
  */
-export const notImplemented = () => {
+export const notImplemented = (): never => {
   throw new Error('not implemented');
 };
 
@@ -350,7 +355,9 @@ export const notImplemented = () => {
  * Memoizes (caches) computation result.
  * Uses WeakMap: the value is going auto-cleaned by GC after last reference is removed.
  */
-export function memoized<T extends object, R, O extends any[]>(fn: (arg: T, ...args: O) => R) {
+export function memoized<T extends object, R, O extends any[]>(
+  fn: (arg: T, ...args: O) => R
+): (arg: T, ...args: O) => R {
   const map = new WeakMap<T, R>();
   return (arg: T, ...args: O): R => {
     const val = map.get(arg);

package/src/abstract/weierstrass.ts

@@ -1,5 +1,30 @@
+/**
+ * Short Weierstrass curve methods. The formula is: y² = x³ + ax + b.
+ *
+ * ### Design rationale for types
+ *
+ * * Interaction between classes from different curves should fail:
+ *   `k256.Point.BASE.add(p256.Point.BASE)`
+ * * For this purpose we want to use `instanceof` operator, which is fast and works during runtime
+ * * Different calls of `curve()` would return different classes -
+ *   `curve(params) !== curve(params)`: if somebody decided to monkey-patch their curve,
+ *   it won't affect others
+ *
+ * TypeScript can't infer types for classes created inside a function. Classes is one instance
+ * of nominative types in TypeScript and interfaces only check for shape, so it's hard to create
+ * unique type for every function call.
+ *
+ * We can use generic types via some param, like curve opts, but that would:
+ *     1. Enable interaction between `curve(params)` and `curve(params)` (curves of same params)
+ *     which is hard to debug.
+ *     2. Params can be generic and we can't enforce them to be constant value:
+ *     if somebody creates curve from non-constant params,
+ *     it would be allowed to interact with other curves with non-constant params
+ *
+ * @todo https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-7.html#unique-symbol
+ * @module
+ */
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
-// Short Weierstrass curve. The formula is: y² = x³ + ax + b
 import {
   AffinePoint,
   BasicCurve,
@@ -44,28 +69,6 @@ function validateSigVerOpts(opts: SignOpts | VerOpts) {
   if (opts.prehash !== undefined) abool('prehash', opts.prehash);
 }
 
-/**
- * ### Design rationale for types
- *
- * * Interaction between classes from different curves should fail:
- *   `k256.Point.BASE.add(p256.Point.BASE)`
- * * For this purpose we want to use `instanceof` operator, which is fast and works during runtime
- * * Different calls of `curve()` would return different classes -
- *   `curve(params) !== curve(params)`: if somebody decided to monkey-patch their curve,
- *   it won't affect others
- *
- * TypeScript can't infer types for classes created inside a function. Classes is one instance of nominative types in TypeScript and interfaces only check for shape, so it's hard to create unique type for every function call.
- *
- * We can use generic types via some param, like curve opts, but that would:
- *     1. Enable interaction between `curve(params)` and `curve(params)` (curves of same params)
- *     which is hard to debug.
- *     2. Params can be generic and we can't enforce them to be constant value:
- *     if somebody creates curve from non-constant params,
- *     it would be allowed to interact with other curves with non-constant params
- *
- * TODO: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-7.html#unique-symbol
- */
-
 // Instance for 3d XYZ points
 export interface ProjPointType<T> extends Group<ProjPointType<T>> {
   readonly px: T;
@@ -102,7 +105,11 @@ export type CurvePointsType<T> = BasicWCurve<T> & {
   toBytes?: (c: ProjConstructor<T>, point: ProjPointType<T>, isCompressed: boolean) => Uint8Array;
 };
 
-function validatePointOpts<T>(curve: CurvePointsType<T>) {
+export type CurvePointsTypeWithLength<T> = Readonly<
+  CurvePointsType<T> & { nByteLength: number; nBitLength: number }
+>;
+
+function validatePointOpts<T>(curve: CurvePointsType<T>): CurvePointsTypeWithLength<T> {
   const opts = validateBasic(curve);
   ut.validateObject(
     opts,
@@ -146,6 +153,31 @@ export type CurvePointsRes<T> = {
 
 const { bytesToNumberBE: b2n, hexToBytes: h2b } = ut;
 
+export class DERErr extends Error {
+  constructor(m = '') {
+    super(m);
+  }
+}
+export type IDER = {
+  // asn.1 DER encoding utils
+  Err: typeof DERErr;
+  // Basic building block is TLV (Tag-Length-Value)
+  _tlv: {
+    encode: (tag: number, data: string) => string;
+    // v - value, l - left bytes (unparsed)
+    decode(tag: number, data: Uint8Array): { v: Uint8Array; l: Uint8Array };
+  };
+  // https://crypto.stackexchange.com/a/57734 Leftmost bit of first byte is 'negative' flag,
+  // since we always use positive integers here. It must always be empty:
+  // - add zero byte if exists
+  // - if next byte doesn't have a flag, leading zero is not allowed (minimal encoding)
+  _int: {
+    encode(num: bigint): string;
+    decode(data: Uint8Array): bigint;
+  };
+  toSig(hex: string | Uint8Array): { r: bigint; s: bigint };
+  hexFromSig(sig: { r: bigint; s: bigint }): string;
+};
 /**
  * ASN.1 DER encoding utilities. ASN is very complex & fragile. Format:
  *
@@ -153,16 +185,12 @@ const { bytesToNumberBE: b2n, hexToBytes: h2b } = ut;
  *
  * Docs: https://letsencrypt.org/docs/a-warm-welcome-to-asn1-and-der/, https://luca.ntop.org/Teaching/Appunti/asn1.html
  */
-export const DER = {
+export const DER: IDER = {
   // asn.1 DER encoding utils
-  Err: class DERErr extends Error {
-    constructor(m = '') {
-      super(m);
-    }
-  },
+  Err: DERErr,
   // Basic building block is TLV (Tag-Length-Value)
   _tlv: {
-    encode: (tag: number, data: string) => {
+    encode: (tag: number, data: string): string => {
       const { Err: E } = DER;
       if (tag < 0 || tag > 256) throw new E('tlv.encode: wrong tag');
       if (data.length & 1) throw new E('tlv.encode: unpadded data');
@@ -206,7 +234,7 @@ export const DER = {
   // - add zero byte if exists
   // - if next byte doesn't have a flag, leading zero is not allowed (minimal encoding)
   _int: {
-    encode(num: bigint) {
+    encode(num: bigint): string {
       const { Err: E } = DER;
       if (num < _0n) throw new E('integer: negative integers are not allowed');
       let hex = ut.numberToHexUnpadded(num);
@@ -737,7 +765,9 @@ export type CurveType = BasicWCurve<bigint> & {
   bits2int_modN?: (bytes: Uint8Array) => bigint;
 };
 
-function validateOpts(curve: CurveType) {
+function validateOpts(
+  curve: CurveType
+): Readonly<CurveType & { nByteLength: number; nBitLength: number }> {
   const opts = validateBasic(curve);
   ut.validateObject(
     opts,
@@ -1214,7 +1244,10 @@ export function weierstrass(curveDef: CurveType): CurveFn {
  * @param Z
  * @returns
  */
-export function SWUFpSqrtRatio<T>(Fp: mod.IField<T>, Z: T) {
+export function SWUFpSqrtRatio<T>(
+  Fp: mod.IField<T>,
+  Z: T
+): (u: T, v: T) => { isValid: boolean; value: T } {
   // Generic implementation
   const q = Fp.ORDER;
   let l = _0n;
@@ -1293,7 +1326,7 @@ export function mapToCurveSimpleSWU<T>(
     B: T;
     Z: T;
   }
-) {
+): (u: T) => { x: T; y: T } {
   mod.validateField(Fp);
   if (!Fp.isValid(opts.A) || !Fp.isValid(opts.B) || !Fp.isValid(opts.Z))
     throw new Error('mapToCurveSimpleSWU: invalid opts');

package/src/bls12-381.ts

@@ -19,61 +19,72 @@ import { AffinePoint, mapToCurveSimpleSWU, ProjPointType } from './abstract/weie
 import { tower12, psiFrobenius } from './abstract/tower.js';
 import type { Fp, Fp2, Fp6, Fp12 } from './abstract/tower.js';
 
-/*
-bls12-381 is pairing-friendly Barreto-Lynn-Scott elliptic curve construction allowing to:
-- Construct zk-SNARKs at the 120-bit security
-- Efficiently verify N aggregate signatures with 1 pairing and N ec additions:
-  the Boneh-Lynn-Shacham signature scheme is orders of magnitude more efficient than Schnorr
-
-### Summary
-1. BLS Relies on Bilinear Pairing (expensive)
-2. Private Keys: 32 bytes
-3. Public Keys: 48 bytes: 381 bit affine x coordinate, encoded into 48 big-endian bytes.
-4. Signatures: 96 bytes: two 381 bit integers (affine x coordinate), encoded into two 48 big-endian byte arrays.
-    - The signature is a point on the G2 subgroup, which is defined over a finite field
-    with elements twice as big as the G1 curve (G2 is over Fp2 rather than Fp. Fp2 is analogous to the complex numbers).
-5. The 12 stands for the Embedding degree.
-
-### Formulas
-- `P = pk x G` - public keys
-- `S = pk x H(m)` - signing
-- `e(P, H(m)) == e(G, S)` - verification using pairings
-- `e(G, S) = e(G, SUM(n)(Si)) = MUL(n)(e(G, Si))` - signature aggregation
-
-### Compatibility and notes
-1. It is compatible with Algorand, Chia, Dfinity, Ethereum, Filecoin, ZEC
-   Filecoin uses little endian byte arrays for private keys - make sure to reverse byte order.
-2. Some projects use G2 for public keys and G1 for signatures. It's called "short signature"
-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),
-[RFC 9380](https://www.rfc-editor.org/rfc/rfc9380).
-*/
+/**
+ * bls12-381 is pairing-friendly Barreto-Lynn-Scott elliptic curve construction allowing to:
+ * * Construct zk-SNARKs at the ~120-bit security
+ * * Efficiently verify N aggregate signatures with 1 pairing and N ec additions:
+ *   the Boneh-Lynn-Shacham signature scheme is orders of magnitude more efficient than Schnorr
+ *
+ * ### Summary
+ * 1. BLS Relies on Bilinear Pairing (expensive)
+ * 2. Private Keys: 32 bytes
+ * 3. Public Keys: 48 bytes: 381 bit affine x coordinate, encoded into 48 big-endian bytes.
+ * 4. Signatures: 96 bytes: two 381 bit integers (affine x coordinate), encoded into two 48 big-endian byte arrays.
+ *     - The signature is a point on the G2 subgroup, which is defined over a finite field
+ *       with elements twice as big as the G1 curve (G2 is over Fp2 rather than Fp. Fp2 is analogous to the
+ *       complex numbers).
+ *     - We also support reversed 96-byte pubkeys & 48-byte short signatures.
+ * 5. The 12 stands for the Embedding degree.
+ *
+ * ### Formulas
+ * - `P = pk x G` - public keys
+ * - `S = pk x H(m)` - signing
+ * - `e(P, H(m)) == e(G, S)` - verification using pairings
+ * - `e(G, S) = e(G, SUM(n)(Si)) = MUL(n)(e(G, Si))` - signature aggregation
+ *
+ * ### Compatibility and notes
+ * 1. It is compatible with Algorand, Chia, Dfinity, Ethereum, Filecoin, ZEC.
+ * Filecoin uses little endian byte arrays for private keys - make sure to reverse byte order.
+ * 2. Some projects use G2 for public keys and G1 for signatures. It's called "short signature".
+ * 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),
+ *    [RFC 9380](https://www.rfc-editor.org/rfc/rfc9380).
+ *
+ * ### Params
+ * To verify curve parameters, see
+ * [pairing-friendly-curves spec](https://datatracker.ietf.org/doc/html/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:
+ * - Fp₁₂ = Fp₆² => Fp₂³
+ * - Fp(u) / (u² - β) where β = -1
+ * - Fp₂(v) / (v³ - ξ) where ξ = u + 1
+ * - Fp₆(w) / (w² - γ) where γ = v
+ * Here goes constants && point encoding format
+ *
+ * Embedding degree (k): 12
+ * Seed (X): -15132376222941642752
+ * Fr:  (x⁴-x²+1)
+ * Fp: ((x-1)² ⋅ r(x)/3+x)
+ * (E/Fp): Y²=X³+4
+ * (Eₜ/Fp²): Y² = X³+4(u+1) (M-type twist)
+ * Ate loop size: X
+ *
+ * ### Towers
+ * - Fp²[u] = Fp/u²+1
+ * - Fp⁶[v] = Fp²/v³-1-u
+ * - Fp¹²[w] = Fp⁶/w²-v
+ *
+ * @todo construct bls & bn fp/fr from seed.
+ * @module
+ */
 
 // 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);
 
-/*
-Embedding degree (k): 12
-Seed (X): -15132376222941642752
-Fr:  (x⁴-x²+1)
-Fp: ((x-1)² ⋅ r(x)/3+x)
-(E/Fp): Y²=X³+4
-(Eₜ/Fp²): Y² = X³+4(u+1) (M-type twist)
-Ate loop size: X
-
-Towers:
-- Fp²[u] = Fp/u²+1
-- Fp⁶[v] = Fp²/v³-1-u
-- Fp¹²[w] = Fp⁶/w²-v
-
-
-TODO: BLS & BN Fp/Fr can be constructed from seed.
-*/
-
 // The BLS parameter x (seed) for BLS12-381. NOTE: it is negative!
 const BLS_X = BigInt('0xd201000000010000');
 const BLS_X_LEN = bitLen(BLS_X);
@@ -418,16 +429,17 @@ function signatureG2ToRawBytes(point: ProjPointType<Fp2>) {
   );
 }
 
-// To verify curve parameters, see pairing-friendly-curves spec:
-// https://datatracker.ietf.org/doc/html/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:
-// Fp₁₂ = Fp₆² => Fp₂³
-// Fp(u) / (u² - β) where β = -1
-// Fp₂(v) / (v³ - ξ) where ξ = u + 1
-// Fp₆(w) / (w² - γ) where γ = v
-// Here goes constants && point encoding format
+/**
+ * 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);
+ */
 export const bls12_381: CurveFn = bls({
   // Fields
   fields: {

package/src/bn254.ts

@@ -1,24 +1,10 @@
-/*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
-import { sha256 } from '@noble/hashes/sha256';
-import { getHash } from './_shortw_utils.js';
-import { weierstrass } from './abstract/weierstrass.js';
-import { randomBytes } from '@noble/hashes/utils';
-import { bls, CurveFn, PostPrecomputeFn, PostPrecomputePointAddFn } from './abstract/bls.js';
-import { Field } from './abstract/modular.js';
-import { bitGet, bitLen, notImplemented } from './abstract/utils.js';
-import { tower12, psiFrobenius } from './abstract/tower.js';
-// Types
-import type { Fp, Fp2, Fp6, Fp12 } from './abstract/tower.js';
-// prettier-ignore
-const _1n = BigInt(1), _2n = BigInt(2), _3n = BigInt(3);
-// prettier-ignore
-const _6n = BigInt(6);
+/**
+ * bn254, previously known as alt_bn_128, when it had 128-bit security.
 
-/*
-bn254, previously known as alt_bn_128, when it had 128-bit security.
 Barbulescu-Duquesne 2017 shown it's weaker: just about 100 bits,
 so the naming has been adjusted to its prime bit count:
-https://hal.science/hal-01534101/file/main.pdf
+https://hal.science/hal-01534101/file/main.pdf.
+Compatible with EIP-196 and EIP-197.
 
 There are huge compatibility issues in the ecosystem:
 
@@ -42,9 +28,8 @@ because it at least has specs:
     - https://github.com/ethereum/py_pairing
     - https://github.com/ethereum/execution-specs/blob/master/src/ethereum/crypto/alt_bn128.py
 - Points are encoded differently in different implementations
-*/
 
-/*
+### Params
 Seed (X): 4965661367192848881
 Fr: (36x⁴+36x³+18x²+6x+1)
 Fp: (36x⁴+36x³+24x²+6x+1)
@@ -52,11 +37,34 @@ Fp: (36x⁴+36x³+24x²+6x+1)
 (Et / Fp²): Y² = X³+3/(u+9) (D-type twist)
 Ate loop size: 6x+2
 
-Towers:
+### Towers
 - Fp²[u] = Fp/u²+1
 - Fp⁶[v] = Fp²/v³-9-u
 - Fp¹²[w] = Fp⁶/w²-v
-*/
+
+ * @module
+ */
+/*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
+import { sha256 } from '@noble/hashes/sha256';
+import { getHash } from './_shortw_utils.js';
+import { CurveFn, weierstrass } from './abstract/weierstrass.js';
+import { randomBytes } from '@noble/hashes/utils';
+import {
+  bls,
+  CurveFn as BLSCurveFn,
+  PostPrecomputeFn,
+  PostPrecomputePointAddFn,
+} from './abstract/bls.js';
+import { Field } from './abstract/modular.js';
+import { bitGet, bitLen, notImplemented } from './abstract/utils.js';
+import { tower12, psiFrobenius } from './abstract/tower.js';
+// Types
+import type { Fp, Fp2, Fp6, Fp12 } from './abstract/tower.js';
+// prettier-ignore
+const _1n = BigInt(1), _2n = BigInt(2), _3n = BigInt(3);
+// prettier-ignore
+const _6n = BigInt(6);
+
 const BN_X = BigInt('4965661367192848881');
 const BN_X_LEN = bitLen(BN_X);
 const SIX_X_SQUARED = _6n * BN_X ** _2n;
@@ -166,7 +174,7 @@ export const _postPrecompute: PostPrecomputeFn = (
  * bn254 (a.k.a. alt_bn128) pairing-friendly curve.
  * Contains G1 / G2 operations and pairings.
  */
-export const bn254: CurveFn = bls({
+export const bn254: BLSCurveFn = bls({
   // Fields
   fields: { Fp, Fp2, Fp6, Fp12, Fr },
   G1: {
@@ -234,7 +242,7 @@ export const bn254: CurveFn = bls({
  * This is very rare and probably not used anywhere.
  * Instead, you should use G1 / G2, defined above.
  */
-export const bn254_weierstrass = weierstrass({
+export const bn254_weierstrass: CurveFn = weierstrass({
   a: BigInt(0),
   b: BigInt(3),
   Fp,