@noble/curves 1.6.0 → 1.8.0

package/src/abstract/hash-to-curve.ts

@@ -1,9 +1,16 @@
+/**
+ * hash-to-curve from [RFC 9380](https://www.rfc-editor.org/rfc/rfc9380).
+ * Hashes arbitrary-length byte strings to a list of one or more elements of a finite field F.
+ * @module
+ */
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
 import type { AffinePoint, Group, GroupConstructor } from './curve.js';
 import { IField, mod } from './modular.js';
 import type { CHash } from './utils.js';
 import { abytes, bytesToNumberBE, concatBytes, utf8ToBytes, validateObject } from './utils.js';
 
+export type UnicodeOrBytes = string | Uint8Array;
+
 /**
  * * `DST` is a domain separation tag, defined in section 2.2.5
  * * `p` characteristic of F, where F is a finite field of characteristic p and order q = p^m
@@ -12,7 +19,6 @@ import { abytes, bytesToNumberBE, concatBytes, utf8ToBytes, validateObject } fro
  * * `expand` is `xmd` (SHA2, SHA3, BLAKE) or `xof` (SHAKE, BLAKE-XOF)
  * * `hash` conforming to `utils.CHash` interface, with `outputLen` / `blockLen` props
  */
-type UnicodeOrBytes = string | Uint8Array;
 export type Opts = {
   DST: UnicodeOrBytes;
   p: bigint;
@@ -29,9 +35,7 @@ const os2ip = bytesToNumberBE;
 function i2osp(value: number, length: number): Uint8Array {
   anum(value);
   anum(length);
-  if (value < 0 || value >= 1 << (8 * length)) {
-    throw new Error(`bad I2OSP call: value=${value} length=${length}`);
-  }
+  if (value < 0 || value >= 1 << (8 * length)) throw new Error('invalid I2OSP input: ' + value);
   const res = Array.from({ length }).fill(0) as number[];
   for (let i = length - 1; i >= 0; i--) {
     res[i] = value & 0xff;
@@ -52,8 +56,10 @@ function anum(item: unknown): void {
   if (!Number.isSafeInteger(item)) throw new Error('number expected');
 }
 
-// Produces a uniformly random byte string using a cryptographic hash function H that outputs b bits
-// https://www.rfc-editor.org/rfc/rfc9380#section-5.3.1
+/**
+ * Produces a uniformly random byte string using a cryptographic hash function H that outputs b bits.
+ * [RFC 9380 5.3.1](https://www.rfc-editor.org/rfc/rfc9380#section-5.3.1).
+ */
 export function expand_message_xmd(
   msg: Uint8Array,
   DST: Uint8Array,
@@ -82,11 +88,13 @@ export function expand_message_xmd(
   return pseudo_random_bytes.slice(0, lenInBytes);
 }
 
-// Produces a uniformly random byte string using an extendable-output function (XOF) H.
-// 1. The collision resistance of H MUST be at least k bits.
-// 2. H MUST be an XOF that has been proved indifferentiable from
-//    a random oracle under a reasonable cryptographic assumption.
-// https://www.rfc-editor.org/rfc/rfc9380#section-5.3.2
+/**
+ * Produces a uniformly random byte string using an extendable-output function (XOF) H.
+ * 1. The collision resistance of H MUST be at least k bits.
+ * 2. H MUST be an XOF that has been proved indifferentiable from
+ *    a random oracle under a reasonable cryptographic assumption.
+ * [RFC 9380 5.3.2](https://www.rfc-editor.org/rfc/rfc9380#section-5.3.2).
+ */
 export function expand_message_xof(
   msg: Uint8Array,
   DST: Uint8Array,
@@ -117,8 +125,8 @@ export function expand_message_xof(
 }
 
 /**
- * Hashes arbitrary-length byte strings to a list of one or more elements of a finite field F
- * https://www.rfc-editor.org/rfc/rfc9380#section-5.2
+ * Hashes arbitrary-length byte strings to a list of one or more elements of a finite field F.
+ * [RFC 9380 5.2](https://www.rfc-editor.org/rfc/rfc9380#section-5.2).
  * @param msg a byte string containing the message to hash
  * @param count the number of elements of F to output
  * @param options `{DST: string, p: bigint, m: number, k: number, expand: 'xmd' | 'xof', hash: H}`, see above
@@ -163,7 +171,14 @@ export function hash_to_field(msg: Uint8Array, count: number, options: Opts): bi
   return u;
 }
 
-export function isogenyMap<T, F extends IField<T>>(field: F, map: [T[], T[], T[], T[]]) {
+export type XY<T> = (
+  x: T,
+  y: T
+) => {
+  x: T;
+  y: T;
+};
+export function isogenyMap<T, F extends IField<T>>(field: F, map: [T[], T[], T[], T[]]): XY<T> {
   // Make same order as in spec
   const COEFF = map.map((i) => Array.from(i).reverse());
   return (x: T, y: T) => {
@@ -172,10 +187,11 @@ export function isogenyMap<T, F extends IField<T>>(field: F, map: [T[], T[], T[]
     );
     x = field.div(xNum, xDen); // xNum / xDen
     y = field.mul(y, field.div(yNum, yDen)); // y * (yNum / yDev)
-    return { x, y };
+    return { x: x, y: y };
   };
 }
 
+/** Point interface, which curves must implement to work correctly with the module. */
 export interface H2CPoint<T> extends Group<H2CPoint<T>> {
   add(rhs: H2CPoint<T>): H2CPoint<T>;
   toAffine(iz?: bigint): AffinePoint<T>;
@@ -192,17 +208,24 @@ export type MapToCurve<T> = (scalar: bigint[]) => AffinePoint<T>;
 // Separated from initialization opts, so users won't accidentally change per-curve parameters
 // (changing DST is ok!)
 export type htfBasicOpts = { DST: UnicodeOrBytes };
+export type HTFMethod<T> = (msg: Uint8Array, options?: htfBasicOpts) => H2CPoint<T>;
+export type MapMethod<T> = (scalars: bigint[]) => H2CPoint<T>;
 
+/** Creates hash-to-curve methods from EC Point and mapToCurve function. */
 export function createHasher<T>(
   Point: H2CPointConstructor<T>,
   mapToCurve: MapToCurve<T>,
   def: Opts & { encodeDST?: UnicodeOrBytes }
-) {
+): {
+  hashToCurve: HTFMethod<T>;
+  encodeToCurve: HTFMethod<T>;
+  mapToCurve: MapMethod<T>;
+} {
   if (typeof mapToCurve !== 'function') throw new Error('mapToCurve() must be defined');
   return {
     // Encodes byte string to elliptic curve.
     // hash_to_curve from https://www.rfc-editor.org/rfc/rfc9380#section-3
-    hashToCurve(msg: Uint8Array, options?: htfBasicOpts) {
+    hashToCurve(msg: Uint8Array, options?: htfBasicOpts): H2CPoint<T> {
       const u = hash_to_field(msg, 2, { ...def, DST: def.DST, ...options } as Opts);
       const u0 = Point.fromAffine(mapToCurve(u[0]));
       const u1 = Point.fromAffine(mapToCurve(u[1]));
@@ -213,18 +236,17 @@ export function createHasher<T>(
 
     // Encodes byte string to elliptic curve.
     // encode_to_curve from https://www.rfc-editor.org/rfc/rfc9380#section-3
-    encodeToCurve(msg: Uint8Array, options?: htfBasicOpts) {
+    encodeToCurve(msg: Uint8Array, options?: htfBasicOpts): H2CPoint<T> {
       const u = hash_to_field(msg, 1, { ...def, DST: def.encodeDST, ...options } as Opts);
       const P = Point.fromAffine(mapToCurve(u[0])).clearCofactor();
       P.assertValidity();
       return P;
     },
     // Same as encodeToCurve, but without hash
-    mapToCurve(scalars: bigint[]) {
+    mapToCurve(scalars: bigint[]): H2CPoint<T> {
       if (!Array.isArray(scalars)) throw new Error('mapToCurve: expected array of bigints');
       for (const i of scalars)
-        if (typeof i !== 'bigint')
-          throw new Error(`mapToCurve: expected array of bigints, got ${i} in array`);
+        if (typeof i !== 'bigint') throw new Error('mapToCurve: expected array of bigints');
       const P = Point.fromAffine(mapToCurve(scalars)).clearCofactor();
       P.assertValidity();
       return P;

package/src/abstract/modular.ts

@@ -1,5 +1,10 @@
+/**
+ * Utils for modular division and finite fields.
+ * A finite field over 11 is integer number operations `mod 11`.
+ * There is no division: it is replaced by modular multiplicative inverse.
+ * @module
+ */
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
-// Utilities for modular arithmetics and finite fields
 import {
   bitMask,
   bytesToNumberBE,
@@ -9,12 +14,13 @@ import {
   numberToBytesLE,
   validateObject,
 } from './utils.js';
+
 // prettier-ignore
-const _0n = BigInt(0), _1n = BigInt(1), _2n = BigInt(2), _3n = BigInt(3);
+const _0n = BigInt(0), _1n = BigInt(1), _2n = /* @__PURE__ */ BigInt(2), _3n = /* @__PURE__ */ BigInt(3);
 // prettier-ignore
-const _4n = BigInt(4), _5n = BigInt(5), _8n = BigInt(8);
+const _4n = /* @__PURE__ */ BigInt(4), _5n = /* @__PURE__ */ BigInt(5), _8n = /* @__PURE__ */ BigInt(8);
 // prettier-ignore
-const _9n = BigInt(9), _16n = BigInt(16);
+const _9n =/* @__PURE__ */ BigInt(9), _16n = /* @__PURE__ */ BigInt(16);
 
 // Calculates a modulo b
 export function mod(a: bigint, b: bigint): bigint {
@@ -24,12 +30,13 @@ export function mod(a: bigint, b: bigint): bigint {
 /**
  * Efficiently raise num to power and do modular division.
  * Unsafe in some contexts: uses ladder, so can expose bigint bits.
+ * @todo use field version && remove
  * @example
  * pow(2n, 6n, 11n) // 64n % 11n == 9n
  */
-// TODO: use field version && remove
 export function pow(num: bigint, power: bigint, modulo: bigint): bigint {
-  if (modulo <= _0n || power < _0n) throw new Error('Expected power/modulo > 0');
+  if (power < _0n) throw new Error('invalid exponent, negatives unsupported');
+  if (modulo <= _0n) throw new Error('invalid modulus');
   if (modulo === _1n) return _0n;
   let res = _1n;
   while (power > _0n) {
@@ -40,7 +47,7 @@ export function pow(num: bigint, power: bigint, modulo: bigint): bigint {
   return res;
 }
 
-// Does x ^ (2 ^ power) mod p. pow2(30, 4) == 30 ^ (2 ^ 4)
+/** Does `x^(2^power)` mod p. `pow2(30, 4)` == `30^(2^4)` */
 export function pow2(x: bigint, power: bigint, modulo: bigint): bigint {
   let res = x;
   while (power-- > _0n) {
@@ -50,12 +57,13 @@ export function pow2(x: bigint, power: bigint, modulo: bigint): bigint {
   return res;
 }
 
-// Inverses number over modulo
+/**
+ * Inverses number over modulo.
+ * Implemented using [Euclidean GCD](https://brilliant.org/wiki/extended-euclidean-algorithm/).
+ */
 export function invert(number: bigint, modulo: bigint): bigint {
-  if (number === _0n || modulo <= _0n) {
-    throw new Error(`invert: expected positive integers, got n=${number} mod=${modulo}`);
-  }
-  // Euclidean GCD https://brilliant.org/wiki/extended-euclidean-algorithm/
+  if (number === _0n) throw new Error('invert: expected non-zero number');
+  if (modulo <= _0n) throw new Error('invert: expected positive modulus, got ' + modulo);
   // Fermat's little theorem "CT-like" version inv(n) = n^(m-2) mod m is 30x slower.
   let a = mod(number, modulo);
   let b = modulo;
@@ -83,7 +91,7 @@ export function invert(number: bigint, modulo: bigint): bigint {
  * @param P field order
  * @returns function that takes field Fp (created from P) and number n
  */
-export function tonelliShanks(P: bigint) {
+export function tonelliShanks(P: bigint): <T>(Fp: IField<T>, n: T) => T {
   // Legendre constant: used to calculate Legendre symbol (a | p),
   // which denotes the value of a^((p-1)/2) (mod p).
   // (a | p) ≡ 1    if a is a square (mod p)
@@ -97,7 +105,10 @@ export function tonelliShanks(P: bigint) {
   for (Q = P - _1n, S = 0; Q % _2n === _0n; Q /= _2n, S++);
 
   // Step 2: Select a non-square z such that (z | p) ≡ -1 and set c ≡ zq
-  for (Z = _2n; Z < P && pow(Z, legendreC, P) !== P - _1n; Z++);
+  for (Z = _2n; Z < P && pow(Z, legendreC, P) !== P - _1n; Z++) {
+    // Crash instead of infinity loop, we cannot reasonable count until P.
+    if (Z > 1000) throw new Error('Cannot find square root: likely non-prime P');
+  }
 
   // Fast-path
   if (S === 1) {
@@ -139,10 +150,18 @@ export function tonelliShanks(P: bigint) {
   };
 }
 
-export function FpSqrt(P: bigint) {
-  // NOTE: different algorithms can give different roots, it is up to user to decide which one they want.
-  // For example there is FpSqrtOdd/FpSqrtEven to choice root based on oddness (used for hash-to-curve).
-
+/**
+ * Square root for a finite field. It will try to check if optimizations are applicable and fall back to 4:
+ *
+ * 1. P ≡ 3 (mod 4)
+ * 2. P ≡ 5 (mod 8)
+ * 3. P ≡ 9 (mod 16)
+ * 4. Tonelli-Shanks algorithm
+ *
+ * Different algorithms can give different roots, it is up to user to decide which one they want.
+ * For example there is FpSqrtOdd/FpSqrtEven to choice root based on oddness (used for hash-to-curve).
+ */
+export function FpSqrt(P: bigint): <T>(Fp: IField<T>, n: T) => T {
   // P ≡ 3 (mod 4)
   // √n = n^((P+1)/4)
   if (P % _4n === _3n) {
@@ -200,11 +219,13 @@ export function FpSqrt(P: bigint) {
 }
 
 // Little-endian check for first LE bit (last BE bit);
-export const isNegativeLE = (num: bigint, modulo: bigint) => (mod(num, modulo) & _1n) === _1n;
+export const isNegativeLE = (num: bigint, modulo: bigint): boolean =>
+  (mod(num, modulo) & _1n) === _1n;
 
-// Field is not always over prime: for example, Fp2 has ORDER(q)=p^m
+/** Field is not always over prime: for example, Fp2 has ORDER(q)=p^m. */
 export interface IField<T> {
   ORDER: bigint;
+  isLE: boolean;
   BYTES: number;
   BITS: number;
   MASK: bigint;
@@ -250,7 +271,7 @@ const FIELD_FIELDS = [
   'eql', 'add', 'sub', 'mul', 'pow', 'div',
   'addN', 'subN', 'mulN', 'sqrN'
 ] as const;
-export function validateField<T>(field: IField<T>) {
+export function validateField<T>(field: IField<T>): IField<T> {
   const initial = {
     ORDER: 'bigint',
     MASK: 'bigint',
@@ -273,7 +294,7 @@ export function validateField<T>(field: IField<T>) {
 export function FpPow<T>(f: IField<T>, num: T, power: bigint): T {
   // Should have same speed as pow for bigints
   // TODO: benchmark!
-  if (power < _0n) throw new Error('Expected power > 0');
+  if (power < _0n) throw new Error('invalid exponent, negatives unsupported');
   if (power === _0n) return f.ONE;
   if (power === _1n) return num;
   let p = f.ONE;
@@ -313,16 +334,19 @@ export function FpDiv<T>(f: IField<T>, lhs: T, rhs: T | bigint): T {
   return f.mul(lhs, typeof rhs === 'bigint' ? invert(rhs, f.ORDER) : f.inv(rhs));
 }
 
-export function FpLegendre(order: bigint) {
-  // (a | p) ≡ 1    if a is a square (mod p), quadratic residue
-  // (a | p) ≡ -1   if a is not a square (mod p), quadratic non residue
-  // (a | p) ≡ 0    if a ≡ 0 (mod p)
+/**
+ * Legendre symbol.
+ * * (a | p) ≡ 1    if a is a square (mod p), quadratic residue
+ * * (a | p) ≡ -1   if a is not a square (mod p), quadratic non residue
+ * * (a | p) ≡ 0    if a ≡ 0 (mod p)
+ */
+export function FpLegendre(order: bigint): <T>(f: IField<T>, x: T) => T {
   const legendreConst = (order - _1n) / _2n; // Integer arithmetic
   return <T>(f: IField<T>, x: T): T => f.pow(x, legendreConst);
 }
 
 // This function returns True whenever the value x is a square in the field F.
-export function FpIsSquare<T>(f: IField<T>) {
+export function FpIsSquare<T>(f: IField<T>): (x: T) => boolean {
   const legendre = FpLegendre(f.ORDER);
   return (x: T): boolean => {
     const p = legendre(f, x);
@@ -331,7 +355,13 @@ export function FpIsSquare<T>(f: IField<T>) {
 }
 
 // CURVE.n lengths
-export function nLength(n: bigint, nBitLength?: number) {
+export function nLength(
+  n: bigint,
+  nBitLength?: number
+): {
+  nBitLength: number;
+  nByteLength: number;
+} {
   // Bit size, byte size of CURVE.n
   const _nBitLength = nBitLength !== undefined ? nBitLength : n.toString(2).length;
   const nByteLength = Math.ceil(_nBitLength / 8);
@@ -340,15 +370,15 @@ export function nLength(n: bigint, nBitLength?: number) {
 
 type FpField = IField<bigint> & Required<Pick<IField<bigint>, 'isOdd'>>;
 /**
- * Initializes a finite field over prime. **Non-primes are not supported.**
- * Do not init in loop: slow. Very fragile: always run a benchmark on a change.
+ * Initializes a finite field over prime.
  * Major performance optimizations:
  * * a) denormalized operations like mulN instead of mul
  * * b) same object shape: never add or remove keys
  * * c) Object.freeze
- * NOTE: operations don't check 'isValid' for all elements for performance reasons,
+ * Fragile: always run a benchmark on a change.
+ * Security note: operations don't check 'isValid' for all elements for performance reasons,
  * it is caller responsibility to check this.
- * This is low-level code, please make sure you know what you doing.
+ * This is low-level code, please make sure you know what you're doing.
  * @param ORDER prime positive bigint
  * @param bitLen how many bits the field consumes
  * @param isLE (def: false) if encoding / decoding should be in little-endian
@@ -360,12 +390,13 @@ export function Field(
   isLE = false,
   redef: Partial<IField<bigint>> = {}
 ): Readonly<FpField> {
-  if (ORDER <= _0n) throw new Error(`Expected Field ORDER > 0, got ${ORDER}`);
+  if (ORDER <= _0n) throw new Error('invalid field: expected ORDER > 0, got ' + ORDER);
   const { nBitLength: BITS, nByteLength: BYTES } = nLength(ORDER, bitLen);
-  if (BYTES > 2048) throw new Error('Field lengths over 2048 bytes are not supported');
-  const sqrtP = FpSqrt(ORDER);
+  if (BYTES > 2048) throw new Error('invalid field: expected ORDER of <= 2048 bytes');
+  let sqrtP: ReturnType<typeof FpSqrt>; // cached sqrtP
   const f: Readonly<FpField> = Object.freeze({
     ORDER,
+    isLE,
     BITS,
     BYTES,
     MASK: bitMask(BITS),
@@ -374,7 +405,7 @@ export function Field(
     create: (num) => mod(num, ORDER),
     isValid: (num) => {
       if (typeof num !== 'bigint')
-        throw new Error(`Invalid field element: expected bigint, got ${typeof num}`);
+        throw new Error('invalid field element: expected bigint, got ' + typeof num);
       return _0n <= num && num < ORDER; // 0 is valid element, but it's not invertible
     },
     is0: (num) => num === _0n,
@@ -396,7 +427,12 @@ export function Field(
     mulN: (lhs, rhs) => lhs * rhs,
 
     inv: (num) => invert(num, ORDER),
-    sqrt: redef.sqrt || ((n) => sqrtP(f, n)),
+    sqrt:
+      redef.sqrt ||
+      ((n) => {
+        if (!sqrtP) sqrtP = FpSqrt(ORDER);
+        return sqrtP(f, n);
+      }),
     invertBatch: (lst) => FpInvertBatch(f, lst),
     // TODO: do we really need constant cmov?
     // We don't have const-time bigints anyway, so probably will be not very useful
@@ -404,21 +440,21 @@ export function Field(
     toBytes: (num) => (isLE ? numberToBytesLE(num, BYTES) : numberToBytesBE(num, BYTES)),
     fromBytes: (bytes) => {
       if (bytes.length !== BYTES)
-        throw new Error(`Fp.fromBytes: expected ${BYTES}, got ${bytes.length}`);
+        throw new Error('Field.fromBytes: expected ' + BYTES + ' bytes, got ' + bytes.length);
       return isLE ? bytesToNumberLE(bytes) : bytesToNumberBE(bytes);
     },
   } as FpField);
   return Object.freeze(f);
 }
 
-export function FpSqrtOdd<T>(Fp: IField<T>, elm: T) {
-  if (!Fp.isOdd) throw new Error(`Field doesn't have isOdd`);
+export function FpSqrtOdd<T>(Fp: IField<T>, elm: T): T {
+  if (!Fp.isOdd) throw new Error("Field doesn't have isOdd");
   const root = Fp.sqrt(elm);
   return Fp.isOdd(root) ? root : Fp.neg(root);
 }
 
-export function FpSqrtEven<T>(Fp: IField<T>, elm: T) {
-  if (!Fp.isOdd) throw new Error(`Field doesn't have isOdd`);
+export function FpSqrtEven<T>(Fp: IField<T>, elm: T): T {
+  if (!Fp.isOdd) throw new Error("Field doesn't have isOdd");
   const root = Fp.sqrt(elm);
   return Fp.isOdd(root) ? Fp.neg(root) : root;
 }
@@ -427,7 +463,7 @@ export function FpSqrtEven<T>(Fp: IField<T>, elm: T) {
  * "Constant-time" private key generation utility.
  * Same as mapKeyToField, but accepts less bytes (40 instead of 48 for 32-byte field).
  * Which makes it slightly more biased, less secure.
- * @deprecated use mapKeyToField instead
+ * @deprecated use `mapKeyToField` instead
  */
 export function hashToPrivateScalar(
   hash: string | Uint8Array,
@@ -438,7 +474,9 @@ export function hashToPrivateScalar(
   const hashLen = hash.length;
   const minLen = nLength(groupOrder).nByteLength + 8;
   if (minLen < 24 || hashLen < minLen || hashLen > 1024)
-    throw new Error(`hashToPrivateScalar: expected ${minLen}-1024 bytes of input, got ${hashLen}`);
+    throw new Error(
+      'hashToPrivateScalar: expected ' + minLen + '-1024 bytes of input, got ' + hashLen
+    );
   const num = isLE ? bytesToNumberLE(hash) : bytesToNumberBE(hash);
   return mod(num, groupOrder - _1n) + _1n;
 }
@@ -486,8 +524,8 @@ export function mapHashToField(key: Uint8Array, fieldOrder: bigint, isLE = false
   const minLen = getMinHashLength(fieldOrder);
   // No small numbers: need to understand bias story. No huge numbers: easier to detect JS timings.
   if (len < 16 || len < minLen || len > 1024)
-    throw new Error(`expected ${minLen}-1024 bytes of input, got ${len}`);
-  const num = isLE ? bytesToNumberBE(key) : bytesToNumberLE(key);
+    throw new Error('expected ' + minLen + '-1024 bytes of input, got ' + len);
+  const num = isLE ? bytesToNumberLE(key) : bytesToNumberBE(key);
   // `mod(x, 11)` can sometimes produce 0. `mod(x, 10) + 1` is the same, but no 0
   const reduced = mod(num, fieldOrder - _1n) + _1n;
   return isLE ? numberToBytesLE(reduced, fieldLen) : numberToBytesBE(reduced, fieldLen);

package/src/abstract/montgomery.ts

@@ -1,3 +1,9 @@
+/**
+ * Montgomery curve methods. It's not really whole montgomery curve,
+ * just bunch of very specific methods for X25519 / X448 from
+ * [RFC 7748](https://www.rfc-editor.org/rfc/rfc7748)
+ * @module
+ */
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
 import { mod, pow } from './modular.js';
 import {
@@ -24,6 +30,7 @@ export type CurveType = {
   Gu: bigint;
   randomBytes?: (bytesLength?: number) => Uint8Array;
 };
+
 export type CurveFn = {
   scalarMult: (scalar: Hex, u: Hex) => Uint8Array;
   scalarMultBase: (scalar: Hex) => Uint8Array;
@@ -52,7 +59,6 @@ function validateOpts(curve: CurveType) {
   return Object.freeze({ ...curve } as const);
 }
 
-// NOTE: not really montgomery curve, just bunch of very specific methods for X25519/X448 (RFC 7748, https://www.rfc-editor.org/rfc/rfc7748)
 // Uses only one coordinate instead of two
 export function montgomery(curveDef: CurveType): CurveFn {
   const CURVE = validateOpts(curveDef);
@@ -158,8 +164,10 @@ export function montgomery(curveDef: CurveType): CurveFn {
   function decodeScalar(n: Hex): bigint {
     const bytes = ensureBytes('scalar', n);
     const len = bytes.length;
-    if (len !== montgomeryBytes && len !== fieldLen)
-      throw new Error(`Expected ${montgomeryBytes} or ${fieldLen} bytes, got ${len}`);
+    if (len !== montgomeryBytes && len !== fieldLen) {
+      let valid = '' + montgomeryBytes + ' or ' + fieldLen;
+      throw new Error('invalid scalar, expected ' + valid + ' bytes, got ' + len);
+    }
     return bytesToNumberLE(adjustScalarBytes(bytes));
   }
   function scalarMult(scalar: Hex, u: Hex): Uint8Array {
@@ -168,7 +176,7 @@ export function montgomery(curveDef: CurveType): CurveFn {
     const pu = montgomeryLadder(pointU, _scalar);
     // The result was not contributory
     // https://cr.yp.to/ecdh.html#validate
-    if (pu === _0n) throw new Error('Invalid private or public key received');
+    if (pu === _0n) throw new Error('invalid private or public key received');
     return encodeUCoordinate(pu);
   }
   // Computes public key from private. By doing scalar multiplication of base point.

package/src/abstract/poseidon.ts

@@ -1,8 +1,14 @@
+/**
+ * Implements [Poseidon](https://www.poseidon-hash.info) ZK-friendly hash.
+ *
+ * There are many poseidon variants with different constants.
+ * We don't provide them: you should construct them manually.
+ * Check out [micro-starknet](https://github.com/paulmillr/micro-starknet) package for a proper example.
+ * @module
+ */
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
-// Poseidon Hash: https://eprint.iacr.org/2019/458.pdf, https://www.poseidon-hash.info
 import { FpPow, IField, validateField } from './modular.js';
-// We don't provide any constants, since different implementations use different constants.
-// For reference constants see './test/poseidon.test.js'.
+
 export type PoseidonOpts = {
   Fp: IField<bigint>;
   t: number;
@@ -14,47 +20,55 @@ export type PoseidonOpts = {
   roundConstants: bigint[][];
 };
 
-export function validateOpts(opts: PoseidonOpts) {
+export function validateOpts(opts: PoseidonOpts): Readonly<{
+  rounds: number;
+  sboxFn: (n: bigint) => bigint;
+  roundConstants: bigint[][];
+  mds: bigint[][];
+  Fp: IField<bigint>;
+  t: number;
+  roundsFull: number;
+  roundsPartial: number;
+  sboxPower?: number;
+  reversePartialPowIdx?: boolean; // Hack for stark
+}> {
   const { Fp, mds, reversePartialPowIdx: rev, roundConstants: rc } = opts;
   const { roundsFull, roundsPartial, sboxPower, t } = opts;
 
   validateField(Fp);
   for (const i of ['t', 'roundsFull', 'roundsPartial'] as const) {
     if (typeof opts[i] !== 'number' || !Number.isSafeInteger(opts[i]))
-      throw new Error(`Poseidon: invalid param ${i}=${opts[i]} (${typeof opts[i]})`);
+      throw new Error('invalid number ' + i);
   }
 
   // MDS is TxT matrix
-  if (!Array.isArray(mds) || mds.length !== t) throw new Error('Poseidon: wrong MDS matrix');
+  if (!Array.isArray(mds) || mds.length !== t) throw new Error('Poseidon: invalid MDS matrix');
   const _mds = mds.map((mdsRow) => {
     if (!Array.isArray(mdsRow) || mdsRow.length !== t)
-      throw new Error(`Poseidon MDS matrix row: ${mdsRow}`);
+      throw new Error('invalid MDS matrix row: ' + mdsRow);
     return mdsRow.map((i) => {
-      if (typeof i !== 'bigint') throw new Error(`Poseidon MDS matrix value=${i}`);
+      if (typeof i !== 'bigint') throw new Error('invalid MDS matrix bigint: ' + i);
       return Fp.create(i);
     });
   });
 
   if (rev !== undefined && typeof rev !== 'boolean')
-    throw new Error(`Poseidon: invalid param reversePartialPowIdx=${rev}`);
+    throw new Error('invalid param reversePartialPowIdx=' + rev);
 
-  if (roundsFull % 2 !== 0) throw new Error(`Poseidon roundsFull is not even: ${roundsFull}`);
+  if (roundsFull & 1) throw new Error('roundsFull is not even' + roundsFull);
   const rounds = roundsFull + roundsPartial;
 
   if (!Array.isArray(rc) || rc.length !== rounds)
-    throw new Error('Poseidon: wrong round constants');
+    throw new Error('Poseidon: invalid round constants');
   const roundConstants = rc.map((rc) => {
-    if (!Array.isArray(rc) || rc.length !== t)
-      throw new Error(`Poseidon wrong round constants: ${rc}`);
+    if (!Array.isArray(rc) || rc.length !== t) throw new Error('invalid round constants');
     return rc.map((i) => {
-      if (typeof i !== 'bigint' || !Fp.isValid(i))
-        throw new Error(`Poseidon wrong round constant=${i}`);
+      if (typeof i !== 'bigint' || !Fp.isValid(i)) throw new Error('invalid round constant');
       return Fp.create(i);
     });
   });
 
-  if (!sboxPower || ![3, 5, 7].includes(sboxPower))
-    throw new Error(`Poseidon wrong sboxPower=${sboxPower}`);
+  if (!sboxPower || ![3, 5, 7].includes(sboxPower)) throw new Error('invalid sboxPower');
   const _sboxPower = BigInt(sboxPower);
   let sboxFn = (n: bigint) => FpPow(Fp, n, _sboxPower);
   // Unwrapped sbox power for common cases (195->142μs)
@@ -64,9 +78,9 @@ export function validateOpts(opts: PoseidonOpts) {
   return Object.freeze({ ...opts, rounds, sboxFn, roundConstants, mds: _mds });
 }
 
-export function splitConstants(rc: bigint[], t: number) {
-  if (typeof t !== 'number') throw new Error('poseidonSplitConstants: wrong t');
-  if (!Array.isArray(rc) || rc.length % t) throw new Error('poseidonSplitConstants: wrong rc');
+export function splitConstants(rc: bigint[], t: number): bigint[][] {
+  if (typeof t !== 'number') throw new Error('poseidonSplitConstants: invalid t');
+  if (!Array.isArray(rc) || rc.length % t) throw new Error('poseidonSplitConstants: invalid rc');
   const res = [];
   let tmp = [];
   for (let i = 0; i < rc.length; i++) {
@@ -79,9 +93,14 @@ export function splitConstants(rc: bigint[], t: number) {
   return res;
 }
 
-export function poseidon(opts: PoseidonOpts) {
+/** Poseidon NTT-friendly hash. */
+export function poseidon(opts: PoseidonOpts): {
+  (values: bigint[]): bigint[];
+  // For verification in tests
+  roundConstants: bigint[][];
+} {
   const _opts = validateOpts(opts);
-  const { Fp, mds, roundConstants, rounds, roundsPartial, sboxFn, t } = _opts;
+  const { Fp, mds, roundConstants, rounds: totalRounds, roundsPartial, sboxFn, t } = _opts;
   const halfRoundsFull = _opts.roundsFull / 2;
   const partialIdx = _opts.reversePartialPowIdx ? t - 1 : 0;
   const poseidonRound = (values: bigint[], isFull: boolean, idx: number) => {
@@ -95,21 +114,20 @@ export function poseidon(opts: PoseidonOpts) {
   };
   const poseidonHash = function poseidonHash(values: bigint[]) {
     if (!Array.isArray(values) || values.length !== t)
-      throw new Error(`Poseidon: wrong values (expected array of bigints with length ${t})`);
+      throw new Error('invalid values, expected array of bigints with length ' + t);
     values = values.map((i) => {
-      if (typeof i !== 'bigint') throw new Error(`Poseidon: wrong value=${i} (${typeof i})`);
+      if (typeof i !== 'bigint') throw new Error('invalid bigint=' + i);
       return Fp.create(i);
     });
-    let round = 0;
+    let lastRound = 0;
     // Apply r_f/2 full rounds.
-    for (let i = 0; i < halfRoundsFull; i++) values = poseidonRound(values, true, round++);
+    for (let i = 0; i < halfRoundsFull; i++) values = poseidonRound(values, true, lastRound++);
     // Apply r_p partial rounds.
-    for (let i = 0; i < roundsPartial; i++) values = poseidonRound(values, false, round++);
+    for (let i = 0; i < roundsPartial; i++) values = poseidonRound(values, false, lastRound++);
     // Apply r_f/2 full rounds.
-    for (let i = 0; i < halfRoundsFull; i++) values = poseidonRound(values, true, round++);
+    for (let i = 0; i < halfRoundsFull; i++) values = poseidonRound(values, true, lastRound++);
 
-    if (round !== rounds)
-      throw new Error(`Poseidon: wrong number of rounds: last round=${round}, total=${rounds}`);
+    if (lastRound !== totalRounds) throw new Error('invalid number of rounds');
     return values;
   };
   // For verification in tests