@noble/curves 1.9.1 → 1.9.3

package/src/abstract/fft.ts

@@ -76,8 +76,15 @@ function findGenerator(field: IField<bigint>) {
   return G;
 }
 
+export type RootsOfUnity = {
+  roots: (bits: number) => bigint[];
+  brp(bits: number): bigint[];
+  inverse(bits: number): bigint[];
+  omega: (bits: number) => bigint;
+  clear: () => void;
+};
 /** We limit roots up to 2**31, which is a lot: 2-billion polynomimal should be rare. */
-export function rootsOfUnity(field: IField<bigint>, generator?: bigint) {
+export function rootsOfUnity(field: IField<bigint>, generator?: bigint): RootsOfUnity {
   // Factor field.ORDER-1 as oddFactor * 2^powerOfTwo
   let oddFactor = field.ORDER - _1n;
   let powerOfTwo = 0;
@@ -186,8 +193,7 @@ export type FFTCoreLoop<T> = <P extends Polynomial<T>>(values: P) => P;
  * Cyclic NTT: Rq = Zq[x]/(x^n-1). butterfly_DIT+loop_DIT OR butterfly_DIF+loop_DIT, roots are omega
  * Negacyclic NTT: Rq = Zq[x]/(x^n+1). butterfly_DIT+loop_DIF, at least for mlkem / mldsa
  */
-export const FFTCore = <T, R>(opts: FFTOpts<T, R>, coreOpts: FFTCoreOpts<R>): FFTCoreLoop<T> => {
-  const { add, sub, mul } = opts; // inline to butteflies
+export const FFTCore = <T, R>(F: FFTOpts<T, R>, coreOpts: FFTCoreOpts<R>): FFTCoreLoop<T> => {
   const { N, roots, dit, invertButterflies = false, skipStages = 0, brp = true } = coreOpts;
   const bits = log2(N);
   if (!isPowerOfTwo(N)) throw new Error('FFT: Polynomial size should be power of two');
@@ -214,15 +220,15 @@ export const FFTCore = <T, R>(opts: FFTOpts<T, R>, coreOpts: FFTCoreOpts<R>): FF
           const a = values[i0];
           // Inlining gives us 10% perf in kyber vs functions
           if (isDit) {
-            const t = mul(b, omega); // Standard DIT butterfly
-            values[i0] = add(a, t);
-            values[i1] = sub(a, t);
+            const t = F.mul(b, omega); // Standard DIT butterfly
+            values[i0] = F.add(a, t);
+            values[i1] = F.sub(a, t);
           } else if (invertButterflies) {
-            values[i0] = add(b, a); // DIT loop + inverted butterflies (Kyber decode)
-            values[i1] = mul(sub(b, a), omega);
+            values[i0] = F.add(b, a); // DIT loop + inverted butterflies (Kyber decode)
+            values[i1] = F.mul(F.sub(b, a), omega);
           } else {
-            values[i0] = add(a, b); // Standard DIF butterfly
-            values[i1] = mul(sub(a, b), omega);
+            values[i0] = F.add(a, b); // Standard DIF butterfly
+            values[i1] = F.mul(F.sub(a, b), omega);
           }
         }
       }
@@ -232,11 +238,16 @@ export const FFTCore = <T, R>(opts: FFTOpts<T, R>, coreOpts: FFTCoreOpts<R>): FF
   };
 };
 
+export type FFTMethods<T> = {
+  direct<P extends Polynomial<T>>(values: P, brpInput?: boolean, brpOutput?: boolean): P;
+  inverse<P extends Polynomial<T>>(values: P, brpInput?: boolean, brpOutput?: boolean): P;
+};
+
 /**
  * NTT aka FFT over finite field (NOT over complex numbers).
  * Naming mirrors other libraries.
  */
-export const FFT = <T>(roots: ReturnType<typeof rootsOfUnity>, opts: FFTOpts<T, bigint>) => {
+export function FFT<T>(roots: RootsOfUnity, opts: FFTOpts<T, bigint>): FFTMethods<T> {
   const getLoop = (
     N: number,
     roots: Polynomial<bigint>,
@@ -272,12 +283,12 @@ export const FFT = <T>(roots: ReturnType<typeof rootsOfUnity>, opts: FFTOpts<T,
       return res;
     },
   };
-};
+}
 
 export type CreatePolyFn<P extends Polynomial<T>, T> = (len: number, elm?: T) => P;
 
 export type PolyFn<P extends Polynomial<T>, T> = {
-  roots: ReturnType<typeof rootsOfUnity>;
+  roots: RootsOfUnity;
   create: CreatePolyFn<P, T>;
   length?: number; // optional enforced size
 
@@ -318,23 +329,23 @@ export type PolyFn<P extends Polynomial<T>, T> = {
  */
 export function poly<T>(
   field: IField<T>,
-  roots: ReturnType<typeof rootsOfUnity>,
+  roots: RootsOfUnity,
   create?: undefined,
-  fft?: ReturnType<typeof FFT<T>>,
+  fft?: FFTMethods<T>,
   length?: number
 ): PolyFn<T[], T>;
 export function poly<T, P extends Polynomial<T>>(
   field: IField<T>,
-  roots: ReturnType<typeof rootsOfUnity>,
+  roots: RootsOfUnity,
   create: CreatePolyFn<P, T>,
-  fft?: ReturnType<typeof FFT<T>>,
+  fft?: FFTMethods<T>,
   length?: number
 ): PolyFn<P, T>;
 export function poly<T, P extends Polynomial<T>>(
   field: IField<T>,
-  roots: ReturnType<typeof rootsOfUnity>,
+  roots: RootsOfUnity,
   create?: CreatePolyFn<P, T>,
-  fft?: ReturnType<typeof FFT<T>>,
+  fft?: FFTMethods<T>,
   length?: number
 ): PolyFn<any, T> {
   const F = field;

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

@@ -5,10 +5,18 @@
  * @module
  */
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
+import type { CHash } from '../utils.ts';
+import {
+  _validateObject,
+  abytes,
+  bytesToNumberBE,
+  concatBytes,
+  isBytes,
+  isHash,
+  utf8ToBytes,
+} from '../utils.ts';
 import type { AffinePoint, Group, GroupConstructor } from './curve.ts';
-import { FpInvertBatch, type IField, mod } from './modular.ts';
-import type { CHash } from './utils.ts';
-import { abytes, bytesToNumberBE, concatBytes, utf8ToBytes, validateObject } from './utils.ts';
+import { FpInvertBatch, mod, type IField } from './modular.ts';
 
 export type UnicodeOrBytes = string | Uint8Array;
 
@@ -20,14 +28,20 @@ export type UnicodeOrBytes = string | Uint8Array;
  * * `expand` is `xmd` (SHA2, SHA3, BLAKE) or `xof` (SHAKE, BLAKE-XOF)
  * * `hash` conforming to `utils.CHash` interface, with `outputLen` / `blockLen` props
  */
-export type Opts = {
+export type H2COpts = {
   DST: UnicodeOrBytes;
+  expand: 'xmd' | 'xof';
+  hash: CHash;
   p: bigint;
   m: number;
   k: number;
+};
+export type H2CHashOpts = {
   expand: 'xmd' | 'xof';
   hash: CHash;
 };
+// todo: remove
+export type Opts = H2COpts;
 
 // Octet Stream to Integer. "spec" implementation of os2ip is 2.5x slower vs bytesToNumberBE.
 const os2ip = bytesToNumberBE;
@@ -57,19 +71,24 @@ function anum(item: unknown): void {
   if (!Number.isSafeInteger(item)) throw new Error('number expected');
 }
 
+function normDST(DST: UnicodeOrBytes): Uint8Array {
+  if (!isBytes(DST) && typeof DST !== 'string') throw new Error('DST must be Uint8Array or string');
+  return typeof DST === 'string' ? utf8ToBytes(DST) : DST;
+}
+
 /**
  * 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,
+  DST: UnicodeOrBytes,
   lenInBytes: number,
   H: CHash
 ): Uint8Array {
   abytes(msg);
-  abytes(DST);
   anum(lenInBytes);
+  DST = normDST(DST);
   // https://www.rfc-editor.org/rfc/rfc9380#section-5.3.3
   if (DST.length > 255) DST = H(concatBytes(utf8ToBytes('H2C-OVERSIZE-DST-'), DST));
   const { outputLen: b_in_bytes, blockLen: r_in_bytes } = H;
@@ -98,14 +117,14 @@ export function expand_message_xmd(
  */
 export function expand_message_xof(
   msg: Uint8Array,
-  DST: Uint8Array,
+  DST: UnicodeOrBytes,
   lenInBytes: number,
   k: number,
   H: CHash
 ): Uint8Array {
   abytes(msg);
-  abytes(DST);
   anum(lenInBytes);
+  DST = normDST(DST);
   // https://www.rfc-editor.org/rfc/rfc9380#section-5.3.3
   // DST = H('H2C-OVERSIZE-DST-' || a_very_long_DST, Math.ceil((lenInBytes * k) / 8));
   if (DST.length > 255) {
@@ -133,18 +152,17 @@ export function expand_message_xof(
  * @param options `{DST: string, p: bigint, m: number, k: number, expand: 'xmd' | 'xof', hash: H}`, see above
  * @returns [u_0, ..., u_(count - 1)], a list of field elements.
  */
-export function hash_to_field(msg: Uint8Array, count: number, options: Opts): bigint[][] {
-  validateObject(options, {
-    DST: 'stringOrUint8Array',
+export function hash_to_field(msg: Uint8Array, count: number, options: H2COpts): bigint[][] {
+  _validateObject(options, {
     p: 'bigint',
-    m: 'isSafeInteger',
-    k: 'isSafeInteger',
-    hash: 'hash',
+    m: 'number',
+    k: 'number',
+    hash: 'function',
   });
-  const { p, k, m, hash, expand, DST: _DST } = options;
+  const { p, k, m, hash, expand, DST } = options;
+  if (!isHash(options.hash)) throw new Error('expected valid hash');
   abytes(msg);
   anum(count);
-  const DST = typeof _DST === 'string' ? utf8ToBytes(_DST) : _DST;
   const log2p = p.toString(2).length;
   const L = Math.ceil((log2p + k) / 8); // section 5.1 of ietf draft link above
   const len_in_bytes = count * m * L;
@@ -209,21 +227,37 @@ 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 H2CMethod<T> = (msg: Uint8Array, options?: htfBasicOpts) => H2CPoint<T>;
+// TODO: remove
+export type HTFMethod<T> = H2CMethod<T>;
 export type MapMethod<T> = (scalars: bigint[]) => H2CPoint<T>;
-export type Hasher<T> = {
-  hashToCurve: HTFMethod<T>;
-  encodeToCurve: HTFMethod<T>;
+export type H2CHasherBase<T> = {
+  hashToCurve: H2CMethod<T>;
+  hashToScalar: (msg: Uint8Array, options: htfBasicOpts) => bigint;
+};
+/**
+ * RFC 9380 methods, with cofactor clearing. See https://www.rfc-editor.org/rfc/rfc9380#section-3.
+ *
+ * * hashToCurve: `map(hash(input))`, encodes RANDOM bytes to curve (WITH hashing)
+ * * encodeToCurve: `map(hash(input))`, encodes NON-UNIFORM bytes to curve (WITH hashing)
+ * * mapToCurve: `map(scalars)`, encodes NON-UNIFORM scalars to curve (NO hashing)
+ */
+export type H2CHasher<T> = H2CHasherBase<T> & {
+  encodeToCurve: H2CMethod<T>;
   mapToCurve: MapMethod<T>;
-  defaults: Opts & { encodeDST?: UnicodeOrBytes };
+  defaults: H2COpts & { encodeDST?: UnicodeOrBytes };
 };
+// TODO: remove
+export type Hasher<T> = H2CHasher<T>;
+
+export const _DST_scalar: Uint8Array = utf8ToBytes('HashToScalar-');
 
-/** Creates hash-to-curve methods from EC Point and mapToCurve function. */
+/** Creates hash-to-curve methods from EC Point and mapToCurve function. See {@link H2CHasher}. */
 export function createHasher<T>(
   Point: H2CPointConstructor<T>,
   mapToCurve: MapToCurve<T>,
-  defaults: Opts & { encodeDST?: UnicodeOrBytes }
-): Hasher<T> {
+  defaults: H2COpts & { encodeDST?: UnicodeOrBytes }
+): H2CHasher<T> {
   if (typeof mapToCurve !== 'function') throw new Error('mapToCurve() must be defined');
   function map(num: bigint[]) {
     return Point.fromAffine(mapToCurve(num));
@@ -238,28 +272,35 @@ export function createHasher<T>(
   return {
     defaults,
 
-    // Encodes byte string to elliptic curve.
-    // hash_to_curve from https://www.rfc-editor.org/rfc/rfc9380#section-3
     hashToCurve(msg: Uint8Array, options?: htfBasicOpts): H2CPoint<T> {
-      const u = hash_to_field(msg, 2, { ...defaults, DST: defaults.DST, ...options } as Opts);
+      const opts = Object.assign({}, defaults, options);
+      const u = hash_to_field(msg, 2, opts);
       const u0 = map(u[0]);
       const u1 = map(u[1]);
       return clear(u0.add(u1));
     },
-
-    // Encodes byte string to elliptic curve.
-    // encode_to_curve from https://www.rfc-editor.org/rfc/rfc9380#section-3
     encodeToCurve(msg: Uint8Array, options?: htfBasicOpts): H2CPoint<T> {
-      const u = hash_to_field(msg, 1, { ...defaults, DST: defaults.encodeDST, ...options } as Opts);
-      return clear(map(u[0]));
+      const optsDst = defaults.encodeDST ? { DST: defaults.encodeDST } : {};
+      const opts = Object.assign({}, defaults, optsDst, options);
+      const u = hash_to_field(msg, 1, opts);
+      const u0 = map(u[0]);
+      return clear(u0);
     },
-
-    // Same as encodeToCurve, but without hash
+    /** See {@link H2CHasher} */
     mapToCurve(scalars: bigint[]): H2CPoint<T> {
       if (!Array.isArray(scalars)) throw new Error('expected array of bigints');
       for (const i of scalars)
         if (typeof i !== 'bigint') throw new Error('expected array of bigints');
       return clear(map(scalars));
     },
+
+    // hash_to_scalar can produce 0: https://www.rfc-editor.org/errata/eid8393
+    // RFC 9380, draft-irtf-cfrg-bbs-signatures-08
+    hashToScalar(msg: Uint8Array, options?: htfBasicOpts): bigint {
+      // @ts-ignore
+      const N = Point.Fn.ORDER;
+      const opts = Object.assign({}, defaults, { p: N, m: 1, DST: _DST_scalar }, options);
+      return hash_to_field(msg, 1, opts)[0][0];
+    },
   };
 }

package/src/abstract/modular.ts

@@ -1,25 +1,27 @@
 /**
- * Utils for modular division and finite fields.
- * A finite field over 11 is integer number operations `mod 11`.
+ * Utils for modular division and fields.
+ * Field over 11 is a finite (Galois) field 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) */
-import { anumber } from '@noble/hashes/utils';
 import {
+  _validateObject,
+  anumber,
   bitMask,
   bytesToNumberBE,
   bytesToNumberLE,
   ensureBytes,
   numberToBytesBE,
   numberToBytesLE,
-  validateObject,
-} from './utils.ts';
+} from '../utils.ts';
 
 // prettier-ignore
 const _0n = BigInt(0), _1n = BigInt(1), _2n = /* @__PURE__ */ BigInt(2), _3n = /* @__PURE__ */ BigInt(3);
 // prettier-ignore
-const _4n = /* @__PURE__ */ BigInt(4), _5n = /* @__PURE__ */ BigInt(5), _8n = /* @__PURE__ */ BigInt(8);
+const _4n = /* @__PURE__ */ BigInt(4), _5n = /* @__PURE__ */ BigInt(5), _7n = /* @__PURE__ */ BigInt(7);
+// prettier-ignore
+const _8n = /* @__PURE__ */ BigInt(8), _9n = /* @__PURE__ */ BigInt(9), _16n = /* @__PURE__ */ BigInt(16);
 
 // Calculates a modulo b
 export function mod(a: bigint, b: bigint): bigint {
@@ -29,7 +31,6 @@ 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: remove.
  * @example
  * pow(2n, 6n, 11n) // 64n % 11n == 9n
  */
@@ -73,6 +74,10 @@ export function invert(number: bigint, modulo: bigint): bigint {
   return mod(x, modulo);
 }
 
+function assertIsSquare<T>(Fp: IField<T>, root: T, n: T): void {
+  if (!Fp.eql(Fp.sqr(root), n)) throw new Error('Cannot find square root');
+}
+
 // Not all roots are possible! Example which will throw:
 // const NUM =
 // n = 72057594037927816n;
@@ -80,8 +85,7 @@ export function invert(number: bigint, modulo: bigint): bigint {
 function sqrt3mod4<T>(Fp: IField<T>, n: T) {
   const p1div4 = (Fp.ORDER + _1n) / _4n;
   const root = Fp.pow(n, p1div4);
-  // Throw if root^2 != n
-  if (!Fp.eql(Fp.sqr(root), n)) throw new Error('Cannot find square root');
+  assertIsSquare(Fp, root, n);
   return root;
 }
 
@@ -92,32 +96,34 @@ function sqrt5mod8<T>(Fp: IField<T>, n: T) {
   const nv = Fp.mul(n, v);
   const i = Fp.mul(Fp.mul(nv, _2n), v);
   const root = Fp.mul(nv, Fp.sub(i, Fp.ONE));
-  if (!Fp.eql(Fp.sqr(root), n)) throw new Error('Cannot find square root');
+  assertIsSquare(Fp, root, n);
   return root;
 }
 
-// TODO: Commented-out for now. Provide test vectors.
-// Tonelli is too slow for extension fields Fp2.
-// That means we can't use sqrt (c1, c2...) even for initialization constants.
-// if (P % _16n === _9n) return sqrt9mod16;
-// // prettier-ignore
-// function sqrt9mod16<T>(Fp: IField<T>, n: T, p7div16?: bigint) {
-//   if (p7div16 === undefined) p7div16 = (Fp.ORDER + BigInt(7)) / _16n;
-//   const c1 = Fp.sqrt(Fp.neg(Fp.ONE)); //  1. c1 = sqrt(-1) in F, i.e., (c1^2) == -1 in F
-//   const c2 = Fp.sqrt(c1);             //  2. c2 = sqrt(c1) in F, i.e., (c2^2) == c1 in F
-//   const c3 = Fp.sqrt(Fp.neg(c1));     //  3. c3 = sqrt(-c1) in F, i.e., (c3^2) == -c1 in F
-//   const c4 = p7div16;                 //  4. c4 = (q + 7) / 16        # Integer arithmetic
-//   let tv1 = Fp.pow(n, c4);            //  1. tv1 = x^c4
-//   let tv2 = Fp.mul(c1, tv1);          //  2. tv2 = c1 * tv1
-//   const tv3 = Fp.mul(c2, tv1);        //  3. tv3 = c2 * tv1
-//   let tv4 = Fp.mul(c3, tv1);          //  4. tv4 = c3 * tv1
-//   const e1 = Fp.eql(Fp.sqr(tv2), n);  //  5.  e1 = (tv2^2) == x
-//   const e2 = Fp.eql(Fp.sqr(tv3), n);  //  6.  e2 = (tv3^2) == x
-//   tv1 = Fp.cmov(tv1, tv2, e1); //  7. tv1 = CMOV(tv1, tv2, e1)  # Select tv2 if (tv2^2) == x
-//   tv2 = Fp.cmov(tv4, tv3, e2); //  8. tv2 = CMOV(tv4, tv3, e2)  # Select tv3 if (tv3^2) == x
-//   const e3 = Fp.eql(Fp.sqr(tv2), n);  //  9.  e3 = (tv2^2) == x
-//   return Fp.cmov(tv1, tv2, e3); // 10.  z = CMOV(tv1, tv2, e3) # Select the sqrt from tv1 and tv2
-// }
+// Based on RFC9380, Kong algorithm
+// prettier-ignore
+function sqrt9mod16(P: bigint): <T>(Fp: IField<T>, n: T) => T {
+  const Fp_ = Field(P);
+  const tn = tonelliShanks(P);
+  const c1 = tn(Fp_, Fp_.neg(Fp_.ONE));//  1. c1 = sqrt(-1) in F, i.e., (c1^2) == -1 in F
+  const c2 = tn(Fp_, c1);              //  2. c2 = sqrt(c1) in F, i.e., (c2^2) == c1 in F
+  const c3 = tn(Fp_, Fp_.neg(c1));     //  3. c3 = sqrt(-c1) in F, i.e., (c3^2) == -c1 in F
+  const c4 = (P + _7n) / _16n;         //  4. c4 = (q + 7) / 16        # Integer arithmetic
+  return <T>(Fp: IField<T>, n: T) => {
+    let tv1 = Fp.pow(n, c4);           //  1. tv1 = x^c4
+    let tv2 = Fp.mul(tv1, c1);         //  2. tv2 = c1 * tv1
+    const tv3 = Fp.mul(tv1, c2);       //  3. tv3 = c2 * tv1
+    const tv4 = Fp.mul(tv1, c3);       //  4. tv4 = c3 * tv1
+    const e1 = Fp.eql(Fp.sqr(tv2), n); //  5.  e1 = (tv2^2) == x
+    const e2 = Fp.eql(Fp.sqr(tv3), n); //  6.  e2 = (tv3^2) == x
+    tv1 = Fp.cmov(tv1, tv2, e1);       //  7. tv1 = CMOV(tv1, tv2, e1)  # Select tv2 if (tv2^2) == x
+    tv2 = Fp.cmov(tv4, tv3, e2);       //  8. tv2 = CMOV(tv4, tv3, e2)  # Select tv3 if (tv3^2) == x
+    const e3 = Fp.eql(Fp.sqr(tv2), n); //  9.  e3 = (tv2^2) == x
+    const root = Fp.cmov(tv1, tv2, e3);// 10.  z = CMOV(tv1, tv2, e3)   # Select sqrt from tv1 & tv2
+    assertIsSquare(Fp, root, n);
+    return root;
+  };
+}
 
 /**
  * Tonelli-Shanks square root search algorithm.
@@ -128,7 +134,8 @@ function sqrt5mod8<T>(Fp: IField<T>, n: T) {
  */
 export function tonelliShanks(P: bigint): <T>(Fp: IField<T>, n: T) => T {
   // Initialization (precomputation).
-  if (P < BigInt(3)) throw new Error('sqrt is not defined for small field');
+  // Caching initialization could boost perf by 7%.
+  if (P < _3n) throw new Error('sqrt is not defined for small field');
   // Factor P - 1 = Q * 2^S, where Q is odd
   let Q = P - _1n;
   let S = 0;
@@ -196,7 +203,8 @@ export function tonelliShanks(P: bigint): <T>(Fp: IField<T>, n: T) => T {
  *
  * 1. P ≡ 3 (mod 4)
  * 2. P ≡ 5 (mod 8)
- * 3. Tonelli-Shanks algorithm
+ * 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).
@@ -206,7 +214,8 @@ export function FpSqrt(P: bigint): <T>(Fp: IField<T>, n: T) => T {
   if (P % _4n === _3n) return sqrt3mod4;
   // P ≡ 5 (mod 8) => Atkin algorithm, page 10 of https://eprint.iacr.org/2012/685.pdf
   if (P % _8n === _5n) return sqrt5mod8;
-  // P ≡ 9 (mod 16) not implemented, see above
+  // P ≡ 9 (mod 16) => Kong algorithm, page 11 of https://eprint.iacr.org/2012/685.pdf (algorithm 4)
+  if (P % _16n === _9n) return sqrt9mod16(P);
   // Tonelli-Shanks algorithm
   return tonelliShanks(P);
 }
@@ -228,6 +237,7 @@ export interface IField<T> {
   create: (num: T) => T;
   isValid: (num: T) => boolean;
   is0: (num: T) => boolean;
+  isValidNot0: (num: T) => boolean;
   neg(num: T): T;
   inv(num: T): T;
   sqrt(num: T): T;
@@ -250,10 +260,11 @@ export interface IField<T> {
   // [RFC9380](https://www.rfc-editor.org/rfc/rfc9380#section-4.1).
   // NOTE: sgn0 is 'negative in LE', which is same as odd. And negative in LE is kinda strange definition anyway.
   isOdd?(num: T): boolean; // Odd instead of even since we have it for Fp2
+  allowedLengths?: number[];
   // legendre?(num: T): T;
   invertBatch: (lst: T[]) => T[];
   toBytes(num: T): Uint8Array;
-  fromBytes(bytes: Uint8Array): T;
+  fromBytes(bytes: Uint8Array, skipValidation?: boolean): T;
   // If c is False, CMOV returns a, otherwise it returns b.
   cmov(a: T, b: T, c: boolean): T;
 }
@@ -267,14 +278,18 @@ export function validateField<T>(field: IField<T>): IField<T> {
   const initial = {
     ORDER: 'bigint',
     MASK: 'bigint',
-    BYTES: 'isSafeInteger',
-    BITS: 'isSafeInteger',
+    BYTES: 'number',
+    BITS: 'number',
   } as Record<string, string>;
   const opts = FIELD_FIELDS.reduce((map, val: string) => {
     map[val] = 'function';
     return map;
   }, initial);
-  return validateObject(field, opts);
+  _validateObject(field, opts);
+  // const max = 16384;
+  // if (field.BYTES < 1 || field.BYTES > max) throw new Error('invalid field');
+  // if (field.BITS < 1 || field.BITS > 8 * max) throw new Error('invalid field');
+  return field;
 }
 
 // Generic field functions
@@ -353,14 +368,9 @@ export function FpIsSquare<T>(Fp: IField<T>, n: T): boolean {
   return l === 1;
 }
 
+export type NLength = { nByteLength: number; nBitLength: number };
 // CURVE.n lengths
-export function nLength(
-  n: bigint,
-  nBitLength?: number
-): {
-  nBitLength: number;
-  nByteLength: number;
-} {
+export function nLength(n: bigint, nBitLength?: number): NLength {
   // Bit size, byte size of CURVE.n
   if (nBitLength !== undefined) anumber(nBitLength);
   const _nBitLength = nBitLength !== undefined ? nBitLength : n.toString(2).length;
@@ -369,29 +379,57 @@ export function nLength(
 }
 
 type FpField = IField<bigint> & Required<Pick<IField<bigint>, 'isOdd'>>;
+type SqrtFn = (n: bigint) => bigint;
+type FieldOpts = Partial<{
+  sqrt: SqrtFn;
+  isLE: boolean;
+  BITS: number;
+  modOnDecode: boolean; // bls12-381 requires mod(n) instead of rejecting keys >= n
+  allowedLengths?: readonly number[]; // for P521 (adds padding for smaller sizes)
+}>;
 /**
- * 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
+ * Creates a finite field. Major performance optimizations:
+ * * 1. Denormalized operations like mulN instead of mul.
+ * * 2. Identical object shape: never add or remove keys.
+ * * 3. `Object.freeze`.
  * 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're doing.
- * @param ORDER prime positive bigint
+ *
+ * Note about field properties:
+ * * CHARACTERISTIC p = prime number, number of elements in main subgroup.
+ * * ORDER q = similar to cofactor in curves, may be composite `q = p^m`.
+ *
+ * @param ORDER field order, probably prime, or could be composite
  * @param bitLen how many bits the field consumes
- * @param isLE (def: false) if encoding / decoding should be in little-endian
+ * @param isLE (default: false) if encoding / decoding should be in little-endian
  * @param redef optional faster redefinitions of sqrt and other methods
  */
 export function Field(
   ORDER: bigint,
-  bitLen?: number,
+  bitLenOrOpts?: number | FieldOpts, // TODO: use opts only in v2?
   isLE = false,
-  redef: Partial<IField<bigint>> = {}
+  opts: { sqrt?: SqrtFn } = {}
 ): Readonly<FpField> {
   if (ORDER <= _0n) throw new Error('invalid field: expected ORDER > 0, got ' + ORDER);
-  const { nBitLength: BITS, nByteLength: BYTES } = nLength(ORDER, bitLen);
+  let _nbitLength: number | undefined = undefined;
+  let _sqrt: SqrtFn | undefined = undefined;
+  let modOnDecode: boolean = false;
+  let allowedLengths: undefined | readonly number[] = undefined;
+  if (typeof bitLenOrOpts === 'object' && bitLenOrOpts != null) {
+    if (opts.sqrt || isLE) throw new Error('cannot specify opts in two arguments');
+    const _opts = bitLenOrOpts;
+    if (_opts.BITS) _nbitLength = _opts.BITS;
+    if (_opts.sqrt) _sqrt = _opts.sqrt;
+    if (typeof _opts.isLE === 'boolean') isLE = _opts.isLE;
+    if (typeof _opts.modOnDecode === 'boolean') modOnDecode = _opts.modOnDecode;
+    allowedLengths = _opts.allowedLengths;
+  } else {
+    if (typeof bitLenOrOpts === 'number') _nbitLength = bitLenOrOpts;
+    if (opts.sqrt) _sqrt = opts.sqrt;
+  }
+  const { nBitLength: BITS, nByteLength: BYTES } = nLength(ORDER, _nbitLength);
   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({
@@ -402,6 +440,7 @@ export function Field(
     MASK: bitMask(BITS),
     ZERO: _0n,
     ONE: _1n,
+    allowedLengths: allowedLengths,
     create: (num) => mod(num, ORDER),
     isValid: (num) => {
       if (typeof num !== 'bigint')
@@ -409,6 +448,8 @@ export function Field(
       return _0n <= num && num < ORDER; // 0 is valid element, but it's not invertible
     },
     is0: (num) => num === _0n,
+    // is valid and invertible
+    isValidNot0: (num: bigint) => !f.is0(num) && f.isValid(num),
     isOdd: (num) => (num & _1n) === _1n,
     neg: (num) => mod(-num, ORDER),
     eql: (lhs, rhs) => lhs === rhs,
@@ -428,16 +469,33 @@ export function Field(
 
     inv: (num) => invert(num, ORDER),
     sqrt:
-      redef.sqrt ||
+      _sqrt ||
       ((n) => {
         if (!sqrtP) sqrtP = FpSqrt(ORDER);
         return sqrtP(f, n);
       }),
     toBytes: (num) => (isLE ? numberToBytesLE(num, BYTES) : numberToBytesBE(num, BYTES)),
-    fromBytes: (bytes) => {
+    fromBytes: (bytes, skipValidation = true) => {
+      if (allowedLengths) {
+        if (!allowedLengths.includes(bytes.length) || bytes.length > BYTES) {
+          throw new Error(
+            'Field.fromBytes: expected ' + allowedLengths + ' bytes, got ' + bytes.length
+          );
+        }
+        const padded = new Uint8Array(BYTES);
+        // isLE add 0 to right, !isLE to the left.
+        padded.set(bytes, isLE ? 0 : padded.length - bytes.length);
+        bytes = padded;
+      }
       if (bytes.length !== BYTES)
         throw new Error('Field.fromBytes: expected ' + BYTES + ' bytes, got ' + bytes.length);
-      return isLE ? bytesToNumberLE(bytes) : bytesToNumberBE(bytes);
+      let scalar = isLE ? bytesToNumberLE(bytes) : bytesToNumberBE(bytes);
+      if (modOnDecode) scalar = mod(scalar, ORDER);
+      if (!skipValidation)
+        if (!f.isValid(scalar)) throw new Error('invalid field element: outside of range 0..ORDER');
+      // NOTE: we don't validate scalar here, please use isValid. This done such way because some
+      // protocol may allow non-reduced scalar that reduced later or changed some other way.
+      return scalar;
     },
     // TODO: we don't need it here, move out to separate fn
     invertBatch: (lst) => FpInvertBatch(f, lst),
@@ -448,6 +506,20 @@ export function Field(
   return Object.freeze(f);
 }
 
+// Generic random scalar, we can do same for other fields if via Fp2.mul(Fp2.ONE, Fp2.random)?
+// This allows unsafe methods like ignore bias or zero. These unsafe, but often used in different protocols (if deterministic RNG).
+// which mean we cannot force this via opts.
+// Not sure what to do with randomBytes, we can accept it inside opts if wanted.
+// Probably need to export getMinHashLength somewhere?
+// random(bytes?: Uint8Array, unsafeAllowZero = false, unsafeAllowBias = false) {
+//   const LEN = !unsafeAllowBias ? getMinHashLength(ORDER) : BYTES;
+//   if (bytes === undefined) bytes = randomBytes(LEN); // _opts.randomBytes?
+//   const num = isLE ? bytesToNumberLE(bytes) : bytesToNumberBE(bytes);
+//   // `mod(x, 11)` can sometimes produce 0. `mod(x, 10) + 1` is the same, but no 0
+//   const reduced = unsafeAllowZero ? mod(num, ORDER) : mod(num, ORDER - _1n) + _1n;
+//   return reduced;
+// },
+
 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);