@noble/curves 2.0.1 → 2.2.0

package/src/bn254.ts

@@ -61,21 +61,27 @@ import {
   type BlsPostPrecomputePointAddFn,
 } from './abstract/bls.ts';
 import { Field, type IField } from './abstract/modular.ts';
-import type { Fp, Fp12, Fp2, Fp6 } from './abstract/tower.ts';
+import type { Fp, Fp12, Fp2 } from './abstract/tower.ts';
 import { psiFrobenius, tower12 } from './abstract/tower.ts';
 import { weierstrass, type WeierstrassOpts } from './abstract/weierstrass.ts';
-import { bitLen } from './utils.ts';
+import { bitLen, type TRet } from './utils.ts';
 // prettier-ignore
-const _0n = BigInt(0), _1n = BigInt(1), _2n = BigInt(2), _3n = BigInt(3);
-const _6n = BigInt(6);
+const _0n = /* @__PURE__ */ BigInt(0), _1n = /* @__PURE__ */ BigInt(1), _2n = /* @__PURE__ */ BigInt(2), _3n = /* @__PURE__ */ BigInt(3);
+const _6n = /* @__PURE__ */ BigInt(6);
 
-const BN_X = BigInt('4965661367192848881');
-const BN_X_LEN = bitLen(BN_X);
-const SIX_X_SQUARED = _6n * BN_X ** _2n;
+// Locally documented BN pairing seed. EIP-197 does not name this scalar
+// directly; noble stores the positive value and derives any `-x` uses later.
+const BN_X = /* @__PURE__ */ BigInt('4965661367192848881');
+// Bit width of the stored seed itself, not the derived Miller-loop scalar `6x+2`.
+const BN_X_LEN = /* @__PURE__ */ (() => bitLen(BN_X))();
+// Derived scalar used by the optimized G2 subgroup test required by EIP-197.
+const SIX_X_SQUARED = /* @__PURE__ */ (() => _6n * BN_X ** _2n)();
 
 const bn254_G1_CURVE: WeierstrassOpts<bigint> = {
   p: BigInt('0x30644e72e131a029b85045b68181585d97816a916871ca8d3c208c16d87cfd47'),
   n: BigInt('0x30644e72e131a029b85045b68181585d2833e84879b9709143e1f593f0000001'),
+  // The Ethereum specs define G1 as prime-order but do not spell out the
+  // cofactor separately; `h = 1` is the implementation-derived value.
   h: _1n,
   a: _0n,
   b: _3n,
@@ -84,42 +90,74 @@ const bn254_G1_CURVE: WeierstrassOpts<bigint> = {
 };
 
 // r == n
-// Finite field over r. It's for convenience and is not used in the code below.
-export const bn254_Fr: IField<bigint> = Field(bn254_G1_CURVE.n);
+// Finite field over r. It's for convenience and is not used in the code below,
+// and its canonical `fromBytes()` decoder is stricter than the EIP-196 MUL
+// scalar rule that accepts any 256-bit integer.
+// These factories are side-effect free; mark them pure so single-export bundles can drop the rest.
+/** bn254 scalar field. */
+export const bn254_Fr: TRet<IField<bigint>> = /* @__PURE__ */ (() =>
+  Field(bn254_G1_CURVE.n) as TRet<IField<bigint>>)();
 
-// Fp2.div(Fp2.mul(Fp2.ONE, _3n), Fp2.NONRESIDUE)
-const Fp2B = {
+// `3 / (i + 9)` from EIP-197, stored in noble's internal `(c0, c1) = (b, a)`
+// order rather than the spec's `a * i + b` notation.
+const Fp2B = /* @__PURE__ */ (() => ({
   c0: BigInt('19485874751759354771024239261021720505790618469301721065564631296452457478373'),
   c1: BigInt('266929791119991161246907387137283842545076965332900288569378510910307636690'),
-};
+}))();
 
-const { Fp, Fp2, Fp6, Fp12 } = tower12({
-  ORDER: bn254_G1_CURVE.p,
-  X_LEN: BN_X_LEN,
-  FP2_NONRESIDUE: [BigInt(9), _1n],
-  Fp2mulByB: (num) => Fp2.mul(num, Fp2B),
-  Fp12finalExponentiate: (num) => {
-    const powMinusX = (num: Fp12) => Fp12.conjugate(Fp12._cyclotomicExp(num, BN_X));
-    const r0 = Fp12.mul(Fp12.conjugate(num), Fp12.inv(num));
-    const r = Fp12.mul(Fp12.frobeniusMap(r0, 2), r0);
-    const y1 = Fp12._cyclotomicSquare(powMinusX(r));
-    const y2 = Fp12.mul(Fp12._cyclotomicSquare(y1), y1);
-    const y4 = powMinusX(y2);
-    const y6 = powMinusX(Fp12._cyclotomicSquare(y4));
-    const y8 = Fp12.mul(Fp12.mul(Fp12.conjugate(y6), y4), Fp12.conjugate(y2));
-    const y9 = Fp12.mul(y8, y1);
-    return Fp12.mul(
-      Fp12.frobeniusMap(Fp12.mul(Fp12.conjugate(r), y9), 3),
-      Fp12.mul(
-        Fp12.frobeniusMap(y8, 2),
-        Fp12.mul(Fp12.frobeniusMap(y9, 1), Fp12.mul(Fp12.mul(y8, y4), r))
-      )
-    );
-  },
-});
+// Bootstrap binding: `Fp12finalExponentiate` needs to reference the finished
+// field object while `tower12(...)` is still constructing it.
+let Fp12: ReturnType<typeof tower12>['Fp12'];
+const tower = /* @__PURE__ */ (() => {
+  const res = tower12({
+    ORDER: bn254_G1_CURVE.p,
+    X_LEN: BN_X_LEN,
+    // Public `Fp2.NONRESIDUE` below is the sextic-tower seed `(9, 1)`, not the
+    // quadratic relation `i^2 + 1 = 0` from the EIP text.
+    FP2_NONRESIDUE: [BigInt(9), _1n],
+    Fp2mulByB: (num: Fp2) => Fp2.mul(num, Fp2B),
+    Fp12finalExponentiate: (num: Fp12) => {
+      const powMinusX = (num: Fp12) => Fp12.conjugate(Fp12._cyclotomicExp(num, BN_X));
+      const r0 = Fp12.mul(Fp12.conjugate(num), Fp12.inv(num));
+      const r = Fp12.mul(Fp12.frobeniusMap(r0, 2), r0);
+      const y1 = Fp12._cyclotomicSquare(powMinusX(r));
+      const y2 = Fp12.mul(Fp12._cyclotomicSquare(y1), y1);
+      const y4 = powMinusX(y2);
+      const y6 = powMinusX(Fp12._cyclotomicSquare(y4));
+      const y8 = Fp12.mul(Fp12.mul(Fp12.conjugate(y6), y4), Fp12.conjugate(y2));
+      const y9 = Fp12.mul(y8, y1);
+      return Fp12.mul(
+        Fp12.frobeniusMap(Fp12.mul(Fp12.conjugate(r), y9), 3),
+        Fp12.mul(
+          Fp12.frobeniusMap(y8, 2),
+          Fp12.mul(Fp12.frobeniusMap(y9, 1), Fp12.mul(Fp12.mul(y8, y4), r))
+        )
+      );
+    },
+  });
+  Fp12 = res.Fp12;
+  return res;
+})();
+const Fp = /* @__PURE__ */ (() => tower.Fp)();
+const Fp2 = /* @__PURE__ */ (() => tower.Fp2)();
 
 // END OF CURVE FIELDS
-const { G2psi, psi } = psiFrobenius(Fp, Fp2, Fp2.NONRESIDUE);
+// BN254 uses the same tower seed `(9, 1)` for the Frobenius helper that powers
+// the divisive-twist G2 endomorphism.
+let frob: ReturnType<typeof psiFrobenius> | undefined;
+const getFrob = () => frob || (frob = psiFrobenius(Fp, Fp2, Fp2.NONRESIDUE));
+// Eager psiFrobenius setup now dominates `bn254.js` import, so defer it to
+// first use. After that these locals are rewritten to the direct helper refs.
+let psi: ReturnType<typeof psiFrobenius>['psi'] = (x, y) => {
+  const fn = getFrob().psi;
+  psi = fn;
+  return fn(x, y);
+};
+let G2psi: ReturnType<typeof psiFrobenius>['G2psi'] = (c, P) => {
+  const fn = getFrob().G2psi;
+  G2psi = fn;
+  return fn(c, P);
+};
 
 export const _postPrecompute: BlsPostPrecomputeFn = (
   Rx: Fp2,
@@ -136,9 +174,11 @@ export const _postPrecompute: BlsPostPrecomputeFn = (
 };
 
 // cofactor: (36 * X^4) + (36 * X^3) + (30 * X^2) + 6*X + 1
-const bn254_G2_CURVE: WeierstrassOpts<Fp2> = {
+const bn254_G2_CURVE: WeierstrassOpts<Fp2> = /* @__PURE__ */ (() => ({
   p: Fp2.ORDER,
   n: bn254_G1_CURVE.n,
+  // As with G1, the Ethereum specs do not spell out the G2 cofactor
+  // separately; this literal is the implementation-derived value.
   h: BigInt('0x30644e72e131a029b85045b68181585e06ceecda572a2489345f2299c0f9fa8d'),
   a: Fp2.ZERO,
   b: Fp2B,
@@ -150,18 +190,24 @@ const bn254_G2_CURVE: WeierstrassOpts<Fp2> = {
     BigInt('8495653923123431417604973247489272438418190587263600148770280649306958101930'),
     BigInt('4082367875863433681332203403145435568316851327593401208105741076214120093531'),
   ]),
-};
+}))();
 
-const fields = { Fp, Fp2, Fp6, Fp12, Fr: bn254_Fr };
-const bn254_G1 = weierstrass(bn254_G1_CURVE, {
+const fields = /* @__PURE__ */ (() => ({ Fp, Fp2, Fp6: tower.Fp6, Fp12, Fr: bn254_Fr }))();
+const bn254_G1 = /* @__PURE__ */ weierstrass(bn254_G1_CURVE, {
   Fp,
   Fn: bn254_Fr,
+  // Ethereum encodes infinity as `(0, 0)`, so the public point API accepts it
+  // even though it is not an affine curve point, and `fromAffine()` stays lazy:
+  // adversarial inputs still need `assertValidity()`.
   allowInfinityPoint: true,
 });
-const bn254_G2 = weierstrass(bn254_G2_CURVE, {
+const bn254_G2 = /* @__PURE__ */ weierstrass(bn254_G2_CURVE, {
   Fp: Fp2,
   Fn: bn254_Fr,
+  // Ethereum encodes infinity as `((0, 0), (0, 0))`, so the public point API
+  // accepts it even though it is not an affine curve point.
   allowInfinityPoint: true,
+  // Optimized BN254 G2 subgroup test used to satisfy the EIP-197 order check.
   isTorsionFree: (c, P) => P.multiplyUnsafe(SIX_X_SQUARED).equals(G2psi(c, P)), // [p]P = [6X^2]P
 });
 /*
@@ -184,13 +230,16 @@ No hashToCurve for now (and signatures):
 // const hasherOpts = {
 //   { ...htfDefaults, m: 1, DST: 'BN254G2_XMD:SHA-256_SVDW_RO_' }
 // };
-const bn254_params = {
+const bn254_params = /* @__PURE__ */ (() => ({
+  // Optimal-ate Miller loop parameter derived from the positive BN seed.
   ateLoopSize: BN_X * _6n + _2n,
   r: bn254_Fr.ORDER,
   xNegative: false,
+  // EIP-197 writes G2 as `y^2 = x^3 + 3 / (i + 9)`, so the pairing
+  // configuration uses the divisive twist convention.
   twistType: 'divisive' as const,
   postPrecompute: _postPrecompute,
-};
+}))();
 // const bn254_hasher = {
 //   hasherOpts: htfDefaults,
 //   hasherOptsG1: { m: 1, DST: 'BN254G2_XMD:SHA-256_SVDW_RO_' },
@@ -213,7 +262,19 @@ const bn254_params = {
 
 /**
  * bn254 (a.k.a. alt_bn128) pairing-friendly curve.
- * Contains G1 / G2 operations and pairings.
+ * Contains G1 / G2 operations and pairings only; the commented-out
+ * hash-to-curve and signature surface is intentionally not exposed here.
+ * @example
+ * Compute a pairing from the two generator points.
+ *
+ * ```ts
+ * const gt = bn254.pairing(bn254.G1.Point.BASE, bn254.G2.Point.BASE);
+ * ```
  */
 // bn254_hasher
-export const bn254: BlsCurvePair = blsBasic(fields, bn254_G1, bn254_G2, bn254_params);
+export const bn254: BlsCurvePair = /* @__PURE__ */ blsBasic(
+  fields,
+  bn254_G1,
+  bn254_G2,
+  bn254_params
+);