@noble/curves 2.0.1 → 2.2.0

package/src/abstract/bls.ts

@@ -15,13 +15,12 @@
  * @module
  **/
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
-import { abytes, memoized, notImplemented, randomBytes } from '../utils.ts';
-import { normalizeZ, type CurveLengths } from './curve.ts';
+import { abytes, notImplemented, randomBytes, type TArg, type TRet } from '../utils.ts';
+import { type CurveLengths } from './curve.ts';
 import {
   createHasher,
   type H2CDSTOpts,
   type H2CHasher,
-  type H2CHashOpts,
   type H2COpts,
   type MapToCurve,
 } from './hash-to-curve.ts';
@@ -34,30 +33,99 @@ type Fp = bigint; // Can be different field?
 // prettier-ignore
 const _0n = BigInt(0), _1n = BigInt(1), _2n = BigInt(2), _3n = BigInt(3);
 
+/**
+ * Twist convention used by the pairing formulas for a concrete curve family.
+ * BLS12-381 uses a multiplicative twist, while BN254 uses a divisive one.
+ */
 export type BlsTwistType = 'multiplicative' | 'divisive';
 
+/**
+ * Codec exposed as `curve.shortSignatures.Signature`.
+ * Use it to parse or serialize G1 signatures in short-signature mode.
+ * In this mode, public keys live in G2.
+ */
 export type BlsShortSignatureCoder<Fp> = {
-  fromBytes(bytes: Uint8Array): WeierstrassPoint<Fp>;
+  /**
+   * Parse a compressed signature from raw bytes.
+   * @param bytes - Compressed signature bytes.
+   * @returns Parsed signature point.
+   */
+  fromBytes(bytes: TArg<Uint8Array>): WeierstrassPoint<Fp>;
+  /**
+   * Parse a compressed signature from a hex string.
+   * @param hex - Compressed signature hex string.
+   * @returns Parsed signature point.
+   */
   fromHex(hex: string): WeierstrassPoint<Fp>;
-  toBytes(point: WeierstrassPoint<Fp>): Uint8Array;
+  /**
+   * Encode a signature point into compressed bytes.
+   * @param point - Signature point.
+   * @returns Compressed signature bytes.
+   */
+  toBytes(point: WeierstrassPoint<Fp>): TRet<Uint8Array>;
+  /**
+   * Encode a signature point into a hex string.
+   * @param point - Signature point.
+   * @returns Compressed signature hex.
+   */
   toHex(point: WeierstrassPoint<Fp>): string;
 };
 
+/**
+ * Codec exposed as `curve.longSignatures.Signature`.
+ * Use it to parse or serialize G2 signatures in long-signature mode.
+ * In this mode, public keys live in G1.
+ */
 export type BlsLongSignatureCoder<Fp> = {
-  fromBytes(bytes: Uint8Array): WeierstrassPoint<Fp>;
+  /**
+   * Parse a compressed signature from raw bytes.
+   * @param bytes - Compressed signature bytes.
+   * @returns Parsed signature point.
+   */
+  fromBytes(bytes: TArg<Uint8Array>): WeierstrassPoint<Fp>;
+  /**
+   * Parse a compressed signature from a hex string.
+   * @param hex - Compressed signature hex string.
+   * @returns Parsed signature point.
+   */
   fromHex(hex: string): WeierstrassPoint<Fp>;
-  toBytes(point: WeierstrassPoint<Fp>): Uint8Array;
+  /**
+   * Encode a signature point into compressed bytes.
+   * @param point - Signature point.
+   * @returns Compressed signature bytes.
+   */
+  toBytes(point: WeierstrassPoint<Fp>): TRet<Uint8Array>;
+  /**
+   * Encode a signature point into a hex string.
+   * @param point - Signature point.
+   * @returns Compressed signature hex.
+   */
   toHex(point: WeierstrassPoint<Fp>): string;
 };
 
+/** Tower fields needed by pairing code, hash-to-curve, and subgroup arithmetic. */
 export type BlsFields = {
+  /** Base field of G1 coordinates. */
   Fp: IField<Fp>;
+  /** Scalar field used for secret scalars and subgroup order arithmetic. */
   Fr: IField<bigint>;
+  /** Quadratic extension field used by G2. */
   Fp2: Fp2Bls;
+  /** Sextic extension field used inside pairing arithmetic. */
   Fp6: Fp6Bls;
+  /** Degree-12 extension field that contains the GT target group. */
   Fp12: Fp12Bls;
 };
 
+/**
+ * Callback used by pairing post-processing hooks to add one more G2 point to the Miller-loop state.
+ * @param Rx - Current projective X coordinate.
+ * @param Ry - Current projective Y coordinate.
+ * @param Rz - Current projective Z coordinate.
+ * @param Qx - G2 affine x coordinate.
+ * @param Qy - G2 affine y coordinate.
+ * @returns Updated projective accumulator coordinates.
+ */
 export type BlsPostPrecomputePointAddFn = (
   Rx: Fp2,
   Ry: Fp2,
@@ -65,6 +133,15 @@ export type BlsPostPrecomputePointAddFn = (
   Qx: Fp2,
   Qy: Fp2
 ) => { Rx: Fp2; Ry: Fp2; Rz: Fp2 };
+/**
+ * Hook for curve-specific pairing cleanup after the Miller loop precomputes are built.
+ * @param Rx - Current projective X coordinate.
+ * @param Ry - Current projective Y coordinate.
+ * @param Rz - Current projective Z coordinate.
+ * @param Qx - G2 affine x coordinate.
+ * @param Qy - G2 affine y coordinate.
+ * @param pointAdd - Callback used to fold one more point into the accumulator.
+ */
 export type BlsPostPrecomputeFn = (
   Rx: Fp2,
   Ry: Fp2,
@@ -73,34 +150,97 @@ export type BlsPostPrecomputeFn = (
   Qy: Fp2,
   pointAdd: BlsPostPrecomputePointAddFn
 ) => void;
+/** Low-level pairing helpers shared by BLS curve bundles. */
 export type BlsPairing = {
+  /** Byte lengths for keys and signatures exposed by this pairing family. */
   lengths: CurveLengths;
+  /** Scalar field used by the pairing and signing helpers. */
   Fr: IField<bigint>;
+  /** Target field used for the GT result of pairings. */
   Fp12: Fp12Bls;
+  /**
+   * Build Miller-loop precomputes for one G2 point.
+   * @param p - G2 point to precompute.
+   * @returns Pairing precompute table.
+   */
   calcPairingPrecomputes: (p: WeierstrassPoint<Fp2>) => Precompute;
+  /**
+   * Evaluate a batch of Miller loops from precomputed line coefficients.
+   * @param pairs - Precomputed Miller-loop inputs.
+   * @returns Accumulated GT value before or after final exponentiation.
+   */
   millerLoopBatch: (pairs: [Precompute, Fp, Fp][]) => Fp12;
+  /**
+   * Pair one G1 point with one G2 point.
+   * @param P - G1 point.
+   * @param Q - G2 point.
+   * @param withFinalExponent - Whether to apply the final exponentiation step.
+   * @returns GT pairing result.
+   * @throws If either point is the point at infinity. {@link Error}
+   */
   pairing: (P: WeierstrassPoint<Fp>, Q: WeierstrassPoint<Fp2>, withFinalExponent?: boolean) => Fp12;
+  /**
+   * Pair many G1/G2 pairs in one batch.
+   * @param pairs - Point pairs to accumulate.
+   * @param withFinalExponent - Whether to apply the final exponentiation step.
+   * @returns GT pairing result. Empty input returns the multiplicative identity in GT.
+   */
   pairingBatch: (
     pairs: { g1: WeierstrassPoint<Fp>; g2: WeierstrassPoint<Fp2> }[],
     withFinalExponent?: boolean
   ) => Fp12;
-  randomSecretKey: (seed?: Uint8Array) => Uint8Array;
+  /**
+   * Generate a random secret key for this pairing family.
+   * @param seed - Optional seed material.
+   * @returns Secret key bytes.
+   */
+  randomSecretKey: (seed?: TArg<Uint8Array>) => TRet<Uint8Array>;
 };
 
+/**
+ * Parameters that define the Miller-loop shape and twist handling
+ * for a concrete pairing family.
+ */
 export type BlsPairingParams = {
   // MSB is always ignored and used as marker for length, otherwise leading zeros will be lost.
   // Can be different from `X` (seed) param.
+  /** Signed loop parameter used by the Miller loop. */
   ateLoopSize: bigint;
+  /** Whether the signed Miller-loop parameter is negative. */
   xNegative: boolean;
-  twistType: BlsTwistType; // BLS12-381: Multiplicative, BN254: Divisive
-  randomBytes?: (len?: number) => Uint8Array;
-  postPrecompute?: BlsPostPrecomputeFn; // Ugly hack to untwist point in BN254 after miller loop
+  /**
+   * Twist convention used by the pairing formulas.
+   * BLS12-381 is multiplicative; BN254 is divisive.
+   */
+  twistType: BlsTwistType;
+  /**
+   * Optional RNG override used by helper constructors.
+   * Receives the requested byte length and returns random bytes.
+   */
+  randomBytes?: (len?: number) => TRet<Uint8Array>;
+  /**
+   * Optional hook for curve-specific untwisting after precomputation.
+   * Used by BN254 after the Miller loop.
+   */
+  postPrecompute?: BlsPostPrecomputeFn;
 };
+/** Hash-to-curve settings shared by the G1 and G2 hashers inside a BLS curve bundle. */
 export type BlsHasherParams = {
+  /**
+   * Optional map-to-curve override for G1.
+   * Receives the hash-to-field tuple and returns one affine G1 point.
+   */
   mapToG1?: MapToCurve<Fp>;
+  /**
+   * Optional map-to-curve override for G2.
+   * Receives the hash-to-field tuple and returns one affine G2 point.
+   */
   mapToG2?: MapToCurve<Fp2>;
+  /** Shared baseline hash-to-curve options. */
   hasherOpts: H2COpts;
+  /** G1-specific hash-to-curve options merged on top of `hasherOpts`. */
   hasherOptsG1: H2COpts;
+  /** G2-specific hash-to-curve options merged on top of `hasherOpts`. */
   hasherOptsG2: H2COpts;
 };
 type PrecomputeSingle = [Fp2, Fp2, Fp2][];
@@ -112,12 +252,35 @@ type Precompute = PrecomputeSingle[];
  * - G2 is a subgroup of ((x₁, x₂+i), (y₁, y₂+i)) E(Fq²) over y² = x³ + 4(1 + i) where i is √-1
  */
 export interface BlsCurvePair {
+  /** Byte lengths for keys and signatures exposed by this curve family. */
   lengths: CurveLengths;
+  /**
+   * Shared Miller-loop batch evaluator.
+   * @param pairs - Precomputed Miller-loop inputs.
+   * @returns Accumulated GT value.
+   */
   millerLoopBatch: BlsPairing['millerLoopBatch'];
+  /**
+   * Pair one G1 point with one G2 point.
+   * @param P - G1 point.
+   * @param Q - G2 point.
+   * @param withFinalExponent - Whether to apply the final exponentiation step.
+   * @returns GT pairing result.
+   * @throws If either point is the point at infinity. {@link Error}
+   */
   pairing: BlsPairing['pairing'];
+  /**
+   * Pair many G1/G2 pairs in one batch.
+   * @param pairs - Point pairs to accumulate.
+   * @param withFinalExponent - Whether to apply the final exponentiation step.
+   * @returns GT pairing result. Empty input returns the multiplicative identity in GT.
+   */
   pairingBatch: BlsPairing['pairingBatch'];
+  /** G1 point constructor for the base field subgroup. */
   G1: { Point: WeierstrassPointCons<Fp> };
+  /** G2 point constructor for the twist subgroup. */
   G2: { Point: WeierstrassPointCons<Fp2> };
+  /** Tower fields exposed by the pairing implementation. */
   fields: {
     Fp: IField<Fp>;
     Fp2: Fp2Bls;
@@ -125,51 +288,112 @@ export interface BlsCurvePair {
     Fp12: Fp12Bls;
     Fr: IField<bigint>;
   };
+  /** Utility helpers shared by hashers and signers. */
   utils: {
-    randomSecretKey: (seed?: Uint8Array) => Uint8Array;
+    randomSecretKey: (seed?: TArg<Uint8Array>) => TRet<Uint8Array>;
     calcPairingPrecomputes: BlsPairing['calcPairingPrecomputes'];
   };
+  /** Public pairing parameters exposed for introspection. */
   params: {
     ateLoopSize: bigint;
     twistType: BlsTwistType;
   };
 }
 
+/** BLS curve bundle extended with hash-to-curve helpers for G1 and G2. */
 export interface BlsCurvePairWithHashers extends BlsCurvePair {
+  /** G1 hasher bundle with RFC 9380 helpers. */
   G1: H2CHasher<WeierstrassPointCons<Fp>>;
+  /** G2 hasher bundle with RFC 9380 helpers. */
   G2: H2CHasher<WeierstrassPointCons<Fp2>>;
 }
 
+/** BLS curve bundle extended with both hashers and signature helpers. */
 export interface BlsCurvePairWithSignatures extends BlsCurvePairWithHashers {
+  /** Long-signature mode: G1 public keys and G2 signatures. */
   longSignatures: BlsSigs<bigint, Fp2>;
+  /** Short-signature mode: G2 public keys and G1 signatures. */
   shortSignatures: BlsSigs<Fp2, bigint>;
 }
 
-type BLSInput = Uint8Array;
+type BLSInput = TArg<Uint8Array>;
+/** BLS signer helpers for one signature mode. */
 export interface BlsSigs<P, S> {
+  /** Byte lengths for secret keys, public keys, and signatures. */
   lengths: CurveLengths;
-  keygen(seed?: Uint8Array): {
-    secretKey: Uint8Array;
+  /**
+   * Generate a secret/public key pair for this signature mode.
+   * @param seed - Optional seed material.
+   * @returns Secret and public key pair.
+   */
+  keygen(seed?: TArg<Uint8Array>): {
+    secretKey: TRet<Uint8Array>;
     publicKey: WeierstrassPoint<P>;
   };
-  getPublicKey(secretKey: Uint8Array): WeierstrassPoint<P>;
-  sign(hashedMessage: WeierstrassPoint<S>, secretKey: Uint8Array): WeierstrassPoint<S>;
+  /**
+   * Derive the public key from a secret key.
+   * @param secretKey - Secret key bytes.
+   * @returns Public-key point.
+   */
+  getPublicKey(secretKey: TArg<Uint8Array>): WeierstrassPoint<P>;
+  /**
+   * Sign a message already hashed onto the signature subgroup.
+   * @param hashedMessage - Message mapped to the signature subgroup.
+   * @param secretKey - Secret key bytes.
+   * @returns Signature point.
+   */
+  sign(hashedMessage: WeierstrassPoint<S>, secretKey: TArg<Uint8Array>): WeierstrassPoint<S>;
+  /**
+   * Verify one signature against one public key and hashed message.
+   * @param signature - Signature point or encoded signature.
+   * @param message - Hashed message point.
+   * @param publicKey - Public-key point or encoded key.
+   * @returns Whether the signature is valid.
+   */
   verify(
     signature: WeierstrassPoint<S> | BLSInput,
     message: WeierstrassPoint<S>,
     publicKey: WeierstrassPoint<P> | BLSInput
   ): boolean;
+  /**
+   * Verify one aggregated signature against many `(message, publicKey)` pairs.
+   * @param signature - Aggregated signature.
+   * @param items - Message/public-key pairs.
+   * @returns Whether the aggregated signature is valid. Same-message aggregate verification still
+   *   requires proof of possession or another rogue-key defense from the caller.
+   */
   verifyBatch: (
     signature: WeierstrassPoint<S> | BLSInput,
     items: { message: WeierstrassPoint<S>; publicKey: WeierstrassPoint<P> | BLSInput }[]
   ) => boolean;
+  /**
+   * Add many public keys into one aggregate point.
+   * @param publicKeys - Public keys to aggregate.
+   * @returns Aggregated public-key point. This is raw point addition and does not add proof of
+   *   possession or rogue-key protection on its own.
+   */
   aggregatePublicKeys(publicKeys: (WeierstrassPoint<P> | BLSInput)[]): WeierstrassPoint<P>;
+  /**
+   * Add many signatures into one aggregate point.
+   * @param signatures - Signatures to aggregate.
+   * @returns Aggregated signature point. This is raw point addition and does not change the proof
+   *   of possession requirements of the aggregate-verification scheme.
+   */
   aggregateSignatures(signatures: (WeierstrassPoint<S> | BLSInput)[]): WeierstrassPoint<S>;
-  hash(message: Uint8Array, DST?: string | Uint8Array, hashOpts?: H2CHashOpts): WeierstrassPoint<S>;
+  /**
+   * Hash an arbitrary message onto the signature subgroup.
+   * @param message - Message bytes.
+   * @param DST - Optional domain separation tag.
+   * @returns Curve point on the signature subgroup.
+   */
+  hash(message: TArg<Uint8Array>, DST?: TArg<string | Uint8Array>): WeierstrassPoint<S>;
+  /** Signature codec for this mode. */
   Signature: BlsLongSignatureCoder<S>;
 }
 
-// Not used with BLS12-381 (no sequential `11` in X). Useful for other curves.
+// Signed non-adjacent decomposition of the spec-defined Miller-loop parameter.
+// BN254 benefits most because `6x+2` has multiple adjacent `11` runs, but BLS12-381's
+// stored `|x|` still starts with `11`, so the Miller loop must also handle one `-1` digit there.
 function NAfDecomposition(a: bigint) {
   const res = [];
   // a>1 because of marker bit
@@ -182,17 +406,19 @@ function NAfDecomposition(a: bigint) {
   }
   return res;
 }
-
 function aNonEmpty(arr: any[]) {
+  // Aggregate helpers use this to reject empty variable-length inputs consistently.
+  // Without the guard, each caller would fall through into a different empty-input / identity
+  // case and hide missing inputs behind outputs that still look structurally valid.
   if (!Array.isArray(arr) || arr.length === 0) throw new Error('expected non-empty array');
 }
 
 // This should be enough for bn254, no need to export full stuff?
 function createBlsPairing(
-  fields: BlsFields,
+  fields: TArg<BlsFields>,
   G1: WeierstrassPointCons<Fp>,
   G2: WeierstrassPointCons<Fp2>,
-  params: BlsPairingParams
+  params: TArg<BlsPairingParams>
 ): BlsPairing {
   const { Fr, Fp2, Fp12 } = fields;
   const { twistType, ateLoopSize, xNegative, postPrecompute } = params;
@@ -224,7 +450,8 @@ function createBlsPairing(
     ell.push([c0, c1, c2]);
 
     Rx = Fp2.mul(Fp2.mul(Fp2.mul(Fp2.sub(t0, t3), Rx), Ry), Fp2div2); // ((T0 - T3) * Rx * Ry) / 2
-    Ry = Fp2.sub(Fp2.sqr(Fp2.mul(Fp2.add(t0, t3), Fp2div2)), Fp2.mul(Fp2.sqr(t2), _3n)); // ((T0 + T3) / 2)² - 3 * T2²
+    // ((T0 + T3) / 2)² - 3 * T2²
+    Ry = Fp2.sub(Fp2.sqr(Fp2.mul(Fp2.add(t0, t3), Fp2div2)), Fp2.mul(Fp2.sqr(t2), _3n));
     Rz = Fp2.mul(t0, t4); // T0 * T4
     return { Rx, Ry, Rz };
   }
@@ -241,7 +468,8 @@ function createBlsPairing(
     const t2 = Fp2.sqr(t1); // T1²
     const t3 = Fp2.mul(t2, t1); // T2 * T1
     const t4 = Fp2.mul(t2, Rx); // T2 * Rx
-    const t5 = Fp2.add(Fp2.sub(t3, Fp2.mul(t4, _2n)), Fp2.mul(Fp2.sqr(t0), Rz)); // T3 - 2 * T4 + T0² * Rz
+    // T3 - 2 * T4 + T0² * Rz
+    const t5 = Fp2.add(Fp2.sub(t3, Fp2.mul(t4, _2n)), Fp2.mul(Fp2.sqr(t0), Rz));
     Rx = Fp2.mul(t1, t5); // T1 * T5
     Ry = Fp2.sub(Fp2.mul(Fp2.sub(t4, t5), t0), Fp2.mul(t3, Ry)); // (T4 - T5) * T0 - T3 * Ry
     Rz = Fp2.mul(Rz, t3); // Rz * T3
@@ -254,7 +482,7 @@ function createBlsPairing(
   // add + double in windowed precomputes here, otherwise it would be single op (since X is static)
   const ATE_NAF = NAfDecomposition(ateLoopSize);
 
-  const calcPairingPrecomputes = memoized((point: G2) => {
+  const calcPairingPrecomputes = (point: G2) => {
     const p = point;
     const { x, y } = p.toAffine();
     // prettier-ignore
@@ -273,7 +501,7 @@ function createBlsPairing(
       postPrecompute(Rx, Ry, Rz, Qx, Qy, pointAdd.bind(null, last));
     }
     return ell;
-  });
+  };
 
   // Main pairing logic is here. Computes product of miller loops + final exponentiate
   // Applies calculated precomputes
@@ -298,16 +526,11 @@ function createBlsPairing(
   // This up to x2 faster than just `map(({g1, g2})=>pairing({g1,g2}))`
   function pairingBatch(pairs: PairingInput[], withFinalExponent: boolean = true) {
     const res: MillerInput = [];
-    // Cache precomputed toAffine for all points
-    normalizeZ(
-      G1,
-      pairs.map(({ g1 }) => g1)
-    );
-    normalizeZ(
-      G2,
-      pairs.map(({ g2 }) => g2)
-    );
     for (const { g1, g2 } of pairs) {
+      // Mathematically, a zero pairing term contributes GT.ONE. We still reject it here because
+      // this API mainly backs BLS verification, where ZERO inputs usually mean broken hash /
+      // wiring. Silently skipping them would turn those failures into a neutral pairing product.
+      // Callers that want the algebraic neutral-element behavior can filter ZERO terms first.
       if (g1.is0() || g2.is0()) throw new Error('pairing is not available for ZERO point');
       // This uses toAffine inside
       g1.assertValidity();
@@ -324,11 +547,15 @@ function createBlsPairing(
   const lengths = {
     seed: getMinHashLength(Fr.ORDER),
   };
-  const rand = params.randomBytes || randomBytes;
-  const randomSecretKey = (seed = rand(lengths.seed)): Uint8Array => {
+  const rand = params.randomBytes === undefined ? randomBytes : params.randomBytes;
+  // Seeded calls deterministically reduce exactly `lengths.seed` bytes into `1..Fr.ORDER-1`;
+  // omitting `seed` just fills that input buffer from the configured RNG first.
+  const randomSecretKey = (seed?: TArg<Uint8Array>): TRet<Uint8Array> => {
+    seed = seed === undefined ? rand(lengths.seed) : seed;
     abytes(seed, lengths.seed, 'seed');
-    return mapHashToField(seed, Fr.ORDER);
+    return mapHashToField(seed, Fr.ORDER) as TRet<Uint8Array>;
   };
+  Object.freeze(lengths);
   return {
     lengths,
     Fr,
@@ -346,7 +573,7 @@ function createBlsSig<P, S>(
   PubPoint: WeierstrassPointCons<P>,
   SigPoint: WeierstrassPointCons<S>,
   isSigG1: boolean,
-  hashToSigCurve: (msg: Uint8Array, options?: H2CDSTOpts) => WeierstrassPoint<S>,
+  hashToSigCurve: (msg: TArg<Uint8Array>, options?: TArg<H2CDSTOpts>) => WeierstrassPoint<S>,
   SignatureCoder?: BlsLongSignatureCoder<S>
 ): BlsSigs<P, S> {
   const { Fr, Fp12, pairingBatch, randomSecretKey, lengths } = blsPairing;
@@ -366,6 +593,9 @@ function createBlsSig<P, S>(
   function normSig(point: SigPoint | BLSInput): SigPoint {
     return point instanceof SigPoint ? (point as SigPoint) : SigPoint.fromBytes(point);
   }
+  // Sign/verify here take points already hashed onto the signature subgroup.
+  // Raw bytes and points from the other subgroup must fail this constructor-brand
+  // check before later validity checks run.
   function amsg(m: unknown): SigPoint {
     if (!(m instanceof SigPoint))
       throw new Error(`expected valid message hashed to ${!isSigG1 ? 'G2' : 'G1'} curve`);
@@ -380,14 +610,14 @@ function createBlsSig<P, S>(
     ? (a: PubPoint, b: SigPoint) => ({ g1: a, g2: b }) as PairingInput
     : (a: PubPoint, b: SigPoint) => ({ g1: b, g2: a }) as PairingInput;
   return Object.freeze({
-    lengths: { ...lengths, secretKey: Fr.BYTES },
-    keygen(seed?: Uint8Array) {
+    lengths: Object.freeze({ ...lengths, secretKey: Fr.BYTES }),
+    keygen(seed?: TArg<Uint8Array>) {
       const secretKey = randomSecretKey(seed);
       const publicKey = this.getPublicKey(secretKey);
       return { secretKey, publicKey };
     },
     // P = pk x G
-    getPublicKey(secretKey: Uint8Array): PubPoint {
+    getPublicKey(secretKey: TArg<Uint8Array>): PubPoint {
       let sec;
       try {
         sec = PubPoint.Fn.fromBytes(secretKey);
@@ -398,7 +628,7 @@ function createBlsSig<P, S>(
       return PubPoint.BASE.multiply(sec);
     },
     // S = pk x H(m)
-    sign(message: SigPoint, secretKey: Uint8Array, unusedArg?: any): SigPoint {
+    sign(message: SigPoint, secretKey: TArg<Uint8Array>, unusedArg?: any): SigPoint {
       if (unusedArg != null) throw new Error('sign() expects 2 arguments');
       const sec = PubPoint.Fn.fromBytes(secretKey);
       amsg(message).assertValidity();
@@ -487,12 +717,12 @@ function createBlsSig<P, S>(
       return agg;
     },
 
-    hash(messageBytes: Uint8Array, DST?: string | Uint8Array): SigPoint {
+    hash(messageBytes: TArg<Uint8Array>, DST?: TArg<string | Uint8Array>): SigPoint {
       abytes(messageBytes);
       const opts = DST ? { DST } : undefined;
       return hashToSigCurve(messageBytes, opts);
     },
-    Signature: SignatureCoder,
+    Signature: Object.freeze({ ...SignatureCoder }),
   }) /*satisfies Signer */;
 }
 
@@ -502,11 +732,30 @@ type BlsSignatureCoders = Partial<{
 }>;
 
 // NOTE: separate function instead of function override, so we don't depend on hasher in bn254.
+/**
+ * @param fields - Tower field implementations.
+ * @param G1_Point - G1 point constructor.
+ * @param G2_Point - G2 point constructor.
+ * @param params - Pairing parameters. See {@link BlsPairingParams}.
+ * @returns Pairing-only BLS helpers. The returned pairing surface rejects infinity inputs, while
+ *   empty `pairingBatch(...)` calls return the multiplicative identity in GT. This keeps the
+ *   low-level pairing API fail-closed for BLS-style callers, where identity points usually signal
+ *   broken hash / wiring instead of an intentionally neutral pairing term. This also eagerly
+ *   precomputes the G1 base-point table as a performance side effect.
+ * @throws If the pairing parameters or underlying curve helpers are inconsistent. {@link Error}
+ * @example
+ * ```ts
+ * import { blsBasic } from '@noble/curves/abstract/bls.js';
+ * import { bn254 } from '@noble/curves/bn254.js';
+ * // Pair a G1 point with a G2 point without the higher-level signer helpers.
+ * const gt = bn254.pairing(bn254.G1.Point.BASE, bn254.G2.Point.BASE);
+ * ```
+ */
 export function blsBasic(
-  fields: BlsFields,
+  fields: TArg<BlsFields>,
   G1_Point: WeierstrassPointCons<Fp>,
   G2_Point: WeierstrassPointCons<Fp2>,
-  params: BlsPairingParams
+  params: TArg<BlsPairingParams>
 ): BlsCurvePair {
   // Fields are specific for curve, so for now we'll need to pass them with opts
   const { Fp, Fr, Fp2, Fp6, Fp12 } = fields;
@@ -527,53 +776,87 @@ export function blsBasic(
   } = pairingRes;
 
   G1.Point.BASE.precompute(4);
+  Object.freeze(G1);
+  Object.freeze(G2);
   return Object.freeze({
-    lengths,
+    lengths: Object.freeze(lengths),
     millerLoopBatch,
     pairing,
     pairingBatch,
     G1,
     G2,
-    fields: { Fr, Fp, Fp2, Fp6, Fp12 },
-    params: {
+    fields: Object.freeze({ Fr, Fp, Fp2, Fp6, Fp12 }),
+    params: Object.freeze({
       ateLoopSize: params.ateLoopSize,
       twistType: params.twistType,
-    },
-    utils: {
+    }),
+    utils: Object.freeze({
       randomSecretKey,
       calcPairingPrecomputes,
-    },
+    }),
   });
 }
 
 // We can export this too, but seems there is not much reasons for now? If user wants hasher, they can just create hasher.
 function blsHashers(
-  fields: BlsFields,
+  fields: TArg<BlsFields>,
   G1_Point: WeierstrassPointCons<Fp>,
   G2_Point: WeierstrassPointCons<Fp2>,
-  params: BlsPairingParams,
-  hasherParams: BlsHasherParams
+  params: TArg<BlsPairingParams>,
+  hasherParams: TArg<BlsHasherParams>
 ): BlsCurvePairWithHashers {
   const base = blsBasic(fields, G1_Point, G2_Point, params);
-  const G1Hasher = createHasher(G1_Point, hasherParams.mapToG1 || notImplemented, {
-    ...hasherParams.hasherOpts,
-    ...hasherParams.hasherOptsG1,
-  });
-  const G2Hasher = createHasher(G2_Point, hasherParams.mapToG2 || notImplemented, {
-    ...hasherParams.hasherOpts,
-    ...hasherParams.hasherOptsG2,
-  });
+  // Missing map hooks intentionally fail closed via notImplemented on first hash use.
+  const G1Hasher = createHasher(
+    G1_Point,
+    hasherParams.mapToG1 === undefined ? notImplemented : hasherParams.mapToG1,
+    {
+      ...hasherParams.hasherOpts,
+      ...hasherParams.hasherOptsG1,
+    }
+  );
+  const G2Hasher = createHasher(
+    G2_Point,
+    hasherParams.mapToG2 === undefined ? notImplemented : hasherParams.mapToG2,
+    {
+      ...hasherParams.hasherOpts,
+      ...hasherParams.hasherOptsG2,
+    }
+  );
   return Object.freeze({ ...base, G1: G1Hasher, G2: G2Hasher });
 }
 
 // G1_Point: ProjConstructor<bigint>, G2_Point: ProjConstructor<Fp2>,
 // Rename to blsSignatures?
+/**
+ * @param fields - Tower field implementations.
+ * @param G1_Point - G1 point constructor.
+ * @param G2_Point - G2 point constructor.
+ * @param params - Pairing parameters. See {@link BlsPairingParams}.
+ * @param hasherParams - Hash-to-curve configuration. See {@link BlsHasherParams}.
+ * @param signatureCoders - Signature codecs.
+ * @returns BLS helpers with signers. The inherited pairing surface still rejects infinity inputs,
+ *   and empty `pairingBatch(...)` calls still return the multiplicative identity in GT. Aggregate
+ *   verification still requires proof of possession or another rogue-key defense from the caller.
+ * @throws If the pairing, hashing, or signature helpers are configured inconsistently. {@link Error}
+ * @example
+ * ```ts
+ * import { bls } from '@noble/curves/abstract/bls.js';
+ * import { bls12_381 } from '@noble/curves/bls12-381.js';
+ * const sigs = bls12_381.longSignatures;
+ * // Use the full BLS helper set when you need hashing, keygen, signing, and verification.
+ * const { secretKey, publicKey } = sigs.keygen();
+ * const msg = sigs.hash(new TextEncoder().encode('hello noble'));
+ * const sig = sigs.sign(msg, secretKey);
+ * const isValid = sigs.verify(sig, msg, publicKey);
+ * ```
+ */
 export function bls(
-  fields: BlsFields,
+  fields: TArg<BlsFields>,
   G1_Point: WeierstrassPointCons<Fp>,
   G2_Point: WeierstrassPointCons<Fp2>,
-  params: BlsPairingParams,
-  hasherParams: BlsHasherParams,
+  params: TArg<BlsPairingParams>,
+  hasherParams: TArg<BlsHasherParams>,
   signatureCoders: BlsSignatureCoders
 ): BlsCurvePairWithSignatures {
   const base = blsHashers(fields, G1_Point, G2_Point, params, hasherParams);