@noble/curves 2.0.0 → 2.2.0

package/src/abstract/poseidon.ts

@@ -7,11 +7,13 @@
  * @module
  */
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
-import { asafenumber, bitGet, validateObject } from '../utils.ts';
+import { asafenumber, bitGet, validateObject, type TArg, type TRet } from '../utils.ts';
 import { FpInvertBatch, FpPow, type IField, validateField } from './modular.ts';
 
 // Grain LFSR (Linear-Feedback Shift Register): https://eprint.iacr.org/2009/109.pdf
 function grainLFSR(state: number[]): () => boolean {
+  // Advances the caller-provided 80-entry state array in place; only the length
+  // is checked here, so entries are assumed to already be bits.
   let pos = 0;
   if (state.length !== 80) throw new Error('grainLFRS: wrong state length, should be 80 bits');
   const getBit = (): boolean => {
@@ -33,15 +35,21 @@ function grainLFSR(state: number[]): () => boolean {
   };
 }
 
+/** Core Poseidon permutation parameters shared by all variants. */
 export type PoseidonBasicOpts = {
+  /** Prime field used by the permutation. */
   Fp: IField<bigint>;
-  t: number; // t = rate + capacity
+  /** Poseidon width `t = rate + capacity`. */
+  t: number;
+  /** Number of full S-box rounds. */
   roundsFull: number;
+  /** Number of partial S-box rounds. */
   roundsPartial: number;
+  /** Whether to use the inverse S-box variant. */
   isSboxInverse?: boolean;
 };
 
-function assertValidPosOpts(opts: PoseidonBasicOpts) {
+function assertValidPosOpts(opts: TArg<PoseidonBasicOpts>) {
   const { Fp, roundsFull } = opts;
   validateField(Fp);
   validateObject(
@@ -59,10 +67,11 @@ function assertValidPosOpts(opts: PoseidonBasicOpts) {
     asafenumber(opts[k], k);
     if (opts[k] < 1) throw new Error('invalid number ' + k);
   }
+  // Poseidon splits full rounds as `R_F / 2`, then partial rounds, then `R_F / 2` again.
   if (roundsFull & 1) throw new Error('roundsFull is not even' + roundsFull);
 }
 
-function poseidonGrain(opts: PoseidonBasicOpts) {
+function poseidonGrain(opts: TArg<PoseidonBasicOpts>) {
   assertValidPosOpts(opts);
   const { Fp } = opts;
   const state = Array(80).fill(1);
@@ -72,6 +81,12 @@ function poseidonGrain(opts: PoseidonBasicOpts) {
   };
   const _0n = BigInt(0);
   const _1n = BigInt(1);
+  // The Grain seed layout is fixed-width: `Fp.BITS` and `t` use 12 bits,
+  // `roundsFull` and `roundsPartial` use 10, so larger values are truncated here.
+  // This is intentional for compatibility with snarkVM / arkworks PoseidonGrainLFSR:
+  // they write the same fixed-width seed fields without range checks, then still consume
+  // the LFSR using the caller-provided round count for ARK/MDS generation.
+  // Normalizing or rejecting here would diverge from those implementations.
   writeBits(_1n, 2); // prime field
   writeBits(opts.isSboxInverse ? _1n : _0n, 4); // b2..b5
   writeBits(BigInt(Fp.BITS), 12); // b6..b17
@@ -98,7 +113,9 @@ function poseidonGrain(opts: PoseidonBasicOpts) {
   };
 }
 
+/** Poseidon settings used by the Grain-LFSR constant generator. */
 export type PoseidonGrainOpts = PoseidonBasicOpts & {
+  /** S-box power used while generating constants. */
   sboxPower?: number;
 };
 
@@ -106,9 +123,32 @@ type PoseidonConstants = { mds: bigint[][]; roundConstants: bigint[][] };
 
 // NOTE: this is not standard but used often for constant generation for poseidon
 // (grain LFRS-like structure)
-export function grainGenConstants(opts: PoseidonGrainOpts, skipMDS: number = 0): PoseidonConstants {
+/**
+ * @param opts - Poseidon grain options. See {@link PoseidonGrainOpts}.
+ * @param skipMDS - Number of MDS samples to skip.
+ * @returns Generated constants.
+ * @throws If the generated MDS matrix contains a zero denominator. {@link Error}
+ * @example
+ * Generate Poseidon round constants and an MDS matrix from the Grain LFSR.
+ *
+ * ```ts
+ * import { grainGenConstants } from '@noble/curves/abstract/poseidon.js';
+ * import { Field } from '@noble/curves/abstract/modular.js';
+ * const Fp = Field(17n);
+ * const constants = grainGenConstants({ Fp, t: 2, roundsFull: 8, roundsPartial: 8 });
+ * ```
+ */
+export function grainGenConstants(
+  opts: TArg<PoseidonGrainOpts>,
+  skipMDS: number = 0
+): PoseidonConstants {
   const { Fp, t, roundsFull, roundsPartial } = opts;
+  // `skipMDS` counts how many candidate matrices to discard before taking one.
+  asafenumber(skipMDS, 'skipMDS');
+  if (skipMDS < 0) throw new Error('invalid number skipMDS');
   const rounds = roundsFull + roundsPartial;
+  // `sboxPower` is carried in the opts shape for Poseidon compatibility, but
+  // Grain constant generation here only depends on field/size/round counts/inverse flag.
   const sample = poseidonGrain(opts);
   const roundConstants: bigint[][] = [];
   for (let r = 0; r < rounds; r++) roundConstants.push(sample(t, true));
@@ -131,24 +171,46 @@ export function grainGenConstants(opts: PoseidonGrainOpts, skipMDS: number = 0):
   return { roundConstants, mds };
 }
 
+/** Fully specified Poseidon permutation options with explicit constants. */
 export type PoseidonOpts = PoseidonBasicOpts &
   PoseidonConstants & {
+    /** S-box power used by the permutation. */
     sboxPower?: number;
+    /** Whether to reverse the partial-round S-box index. */
     reversePartialPowIdx?: boolean; // Hack for stark
   };
 
-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
-}> {
+/**
+ * @param opts - Poseidon options. See {@link PoseidonOpts}.
+ * @returns Normalized poseidon options.
+ * @throws If the Poseidon options, constants, or MDS matrix are invalid. {@link Error}
+ * @example
+ * Validate generated constants before constructing a permutation.
+ *
+ * ```ts
+ * import { grainGenConstants, validateOpts } from '@noble/curves/abstract/poseidon.js';
+ * import { Field } from '@noble/curves/abstract/modular.js';
+ * const Fp = Field(17n);
+ * const constants = grainGenConstants({ Fp, t: 2, roundsFull: 8, roundsPartial: 8 });
+ * const opts = validateOpts({ ...constants, Fp, t: 2, roundsFull: 8, roundsPartial: 8, sboxPower: 3 });
+ * ```
+ */
+export function validateOpts(opts: TArg<PoseidonOpts>): TRet<
+  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
+  }>
+> {
+  // This only normalizes shapes and field membership for the provided constants;
+  // it does not prove the stronger MDS/security criteria discussed in the specs.
   assertValidPosOpts(opts);
   const { Fp, mds, reversePartialPowIdx: rev, roundConstants: rc } = opts;
   const { roundsFull, roundsPartial, sboxPower, t } = opts;
@@ -160,6 +222,8 @@ export function validateOpts(opts: PoseidonOpts): Readonly<{
       throw new Error('invalid MDS matrix row: ' + mdsRow);
     return mdsRow.map((i) => {
       if (typeof i !== 'bigint') throw new Error('invalid MDS matrix bigint: ' + i);
+      // Hardcoded Poseidon MDS matrices often use signed entries like `-1`;
+      // accept bigint representatives here and reduce them into the field.
       return Fp.create(i);
     });
   });
@@ -179,6 +243,9 @@ export function validateOpts(opts: PoseidonOpts): Readonly<{
       return Fp.create(i);
     });
   });
+  // Freeze nested constants so exported handles cannot retune a live permutation instance.
+  const freezeRows = (rows: bigint[][]) =>
+    Object.freeze(rows.map((row) => Object.freeze(row))) as unknown as bigint[][];
 
   if (!sboxPower || ![3, 5, 7, 17].includes(sboxPower)) throw new Error('invalid sboxPower');
   const _sboxPower = BigInt(sboxPower);
@@ -187,16 +254,50 @@ export function validateOpts(opts: PoseidonOpts): Readonly<{
   if (sboxPower === 3) sboxFn = (n: bigint) => Fp.mul(Fp.sqrN(n), n);
   else if (sboxPower === 5) sboxFn = (n: bigint) => Fp.mul(Fp.sqrN(Fp.sqrN(n)), n);
 
-  return Object.freeze({ ...opts, rounds, sboxFn, roundConstants, mds: _mds });
+  return Object.freeze({
+    ...opts,
+    rounds,
+    sboxFn,
+    roundConstants: freezeRows(roundConstants),
+    mds: freezeRows(_mds),
+  }) as TRet<
+    Readonly<{
+      rounds: number;
+      sboxFn: (n: bigint) => bigint;
+      roundConstants: bigint[][];
+      mds: bigint[][];
+      Fp: IField<bigint>;
+      t: number;
+      roundsFull: number;
+      roundsPartial: number;
+      sboxPower?: number;
+      reversePartialPowIdx?: boolean;
+    }>
+  >;
 }
 
+/**
+ * @param rc - Flattened round constants.
+ * @param t - Poseidon width.
+ * @returns Constants grouped by round.
+ * @throws If the width or flattened constant array is invalid. {@link Error}
+ * @example
+ * Regroup a flat constant list into per-round chunks.
+ *
+ * ```ts
+ * const rounds = splitConstants([1n, 2n, 3n, 4n], 2);
+ * ```
+ */
 export function splitConstants(rc: bigint[], t: number): bigint[][] {
-  if (typeof t !== 'number') throw new Error('poseidonSplitConstants: invalid t');
+  asafenumber(t, 't');
+  if (t < 1) 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++) {
-    tmp.push(rc[i]);
+    const c = rc[i];
+    if (typeof c !== 'bigint') throw new Error('invalid bigint=' + c);
+    tmp.push(c);
     if (tmp.length === t) {
       res.push(tmp);
       tmp = [];
@@ -205,13 +306,34 @@ export function splitConstants(rc: bigint[], t: number): bigint[][] {
   return res;
 }
 
+/**
+ * Poseidon permutation callable.
+ * @param values - Poseidon state vector. Non-canonical bigints are normalized with `Fp.create(...)`.
+ * @returns Permuted state vector.
+ */
 export type PoseidonFn = {
   (values: bigint[]): bigint[];
-  // For verification in tests
+  /** Round constants captured by the permutation instance. */
   roundConstants: bigint[][];
 };
 /** Poseidon NTT-friendly hash. */
-export function poseidon(opts: PoseidonOpts): PoseidonFn {
+/**
+ * @param opts - Poseidon options. See {@link PoseidonOpts}.
+ * @returns Poseidon permutation.
+ * @throws If the Poseidon options or state vector are invalid. {@link Error}
+ * @example
+ * Build a Poseidon permutation from validated parameters and constants.
+ *
+ * ```ts
+ * import { grainGenConstants, poseidon } from '@noble/curves/abstract/poseidon.js';
+ * import { Field } from '@noble/curves/abstract/modular.js';
+ * const Fp = Field(17n);
+ * const constants = grainGenConstants({ Fp, t: 2, roundsFull: 8, roundsPartial: 8 });
+ * const hash = poseidon({ ...constants, Fp, t: 2, roundsFull: 8, roundsPartial: 8, sboxPower: 3 });
+ * const state = hash([1n, 2n]);
+ * ```
+ */
+export function poseidon(opts: TArg<PoseidonOpts>): PoseidonFn {
   const _opts = validateOpts(opts);
   const { Fp, mds, roundConstants, rounds: totalRounds, roundsPartial, sboxFn, t } = _opts;
   const halfRoundsFull = _opts.roundsFull / 2;
@@ -228,10 +350,13 @@ export function poseidon(opts: PoseidonOpts): PoseidonFn {
   const poseidonHash = function poseidonHash(values: bigint[]) {
     if (!Array.isArray(values) || values.length !== t)
       throw new Error('invalid values, expected array of bigints with length ' + t);
-    values = values.map((i) => {
+    // `.map()` skips sparse holes, which would leak `undefined` into round math below.
+    values = values.slice();
+    for (let j = 0; j < values.length; j++) {
+      const i = values[j];
       if (typeof i !== 'bigint') throw new Error('invalid bigint=' + i);
-      return Fp.create(i);
-    });
+      values[j] = Fp.create(i);
+    }
     let lastRound = 0;
     // Apply r_f/2 full rounds.
     for (let i = 0; i < halfRoundsFull; i++) values = poseidonRound(values, true, lastRound++);
@@ -242,12 +367,34 @@ export function poseidon(opts: PoseidonOpts): PoseidonFn {
 
     if (lastRound !== totalRounds) throw new Error('invalid number of rounds');
     return values;
-  };
+  } as PoseidonFn;
   // For verification in tests
-  poseidonHash.roundConstants = roundConstants;
+  Object.defineProperty(poseidonHash, 'roundConstants', {
+    value: roundConstants,
+    enumerable: true,
+  });
   return poseidonHash;
 }
 
+/**
+ * @param Fp - Field implementation.
+ * @param rate - Sponge rate.
+ * @param capacity - Sponge capacity.
+ * @param hash - Poseidon permutation.
+ * @example
+ * Wrap one Poseidon permutation in a sponge interface.
+ *
+ * ```ts
+ * import { PoseidonSponge, grainGenConstants, poseidon } from '@noble/curves/abstract/poseidon.js';
+ * import { Field } from '@noble/curves/abstract/modular.js';
+ * const Fp = Field(17n);
+ * const constants = grainGenConstants({ Fp, t: 2, roundsFull: 8, roundsPartial: 8 });
+ * const hash = poseidon({ ...constants, Fp, t: 2, roundsFull: 8, roundsPartial: 8, sboxPower: 3 });
+ * const sponge = new PoseidonSponge(Fp, 1, 1, hash);
+ * sponge.absorb([1n]);
+ * const out = sponge.squeeze(1);
+ * ```
+ */
 export class PoseidonSponge {
   private Fp: IField<bigint>;
   readonly rate: number;
@@ -258,14 +405,24 @@ export class PoseidonSponge {
   private isAbsorbing = true;
 
   constructor(Fp: IField<bigint>, rate: number, capacity: number, hash: PoseidonFn) {
+    const width = spongeShape(rate, capacity);
+    // The direct constructor accepts an arbitrary permutation hook, but callers still
+    // need to preserve the `PoseidonFn.roundConstants` width metadata. Reject width
+    // mismatches here instead of deferring them until the first `process()` call.
+    if (width !== hash.roundConstants[0]?.length)
+      throw new Error(
+        `invalid sponge width: expected ${hash.roundConstants[0]?.length}, got ${width}`
+      );
     this.Fp = Fp;
     this.hash = hash;
     this.rate = rate;
     this.capacity = capacity;
-    this.state = new Array(rate + capacity);
+    this.state = new Array(width);
     this.clean();
   }
   private process(): void {
+    // The permutation is expected to return an owned state array. If callers inject a custom
+    // hook that reuses external storage, `clean()` will zero that shared buffer too.
     this.state = this.hash(this.state);
   }
   absorb(input: bigint[]): void {
@@ -285,6 +442,10 @@ export class PoseidonSponge {
     }
   }
   squeeze(count: number): bigint[] {
+    // Rust oracles use unsigned counts. In JS we keep `squeeze(0) => []` for
+    // compatibility, but still reject negative/fractional counts explicitly.
+    asafenumber(count, 'count');
+    if (count < 0) throw new Error('invalid number count');
     const res: bigint[] = [];
     while (res.length < count) {
       if (this.isAbsorbing || this.pos === this.rate) {
@@ -305,29 +466,68 @@ export class PoseidonSponge {
   clone(): PoseidonSponge {
     const c = new PoseidonSponge(this.Fp, this.rate, this.capacity, this.hash);
     c.pos = this.pos;
+    c.isAbsorbing = this.isAbsorbing;
     c.state = [...this.state];
     return c;
   }
 }
 
+/** Options for the non-standard but commonly used Poseidon sponge wrapper. */
 export type PoseidonSpongeOpts = Omit<PoseidonOpts, 't'> & {
+  /** Sponge rate. */
   rate: number;
+  /** Sponge capacity. */
   capacity: number;
 };
 
+const spongeShape = (rate: number, capacity: number) => {
+  asafenumber(rate, 'rate');
+  asafenumber(capacity, 'capacity');
+  // A sponge with zero rate cannot absorb or squeeze any field elements.
+  if (rate < 1) throw new Error('invalid number rate');
+  // Negative capacity can accidentally keep `rate + capacity` coherent while still
+  // producing a nonsensical sponge shape.
+  if (capacity < 0) throw new Error('invalid number capacity');
+  return rate + capacity;
+};
+
 /**
  * The method is not defined in spec, but nevertheless used often.
  * Check carefully for compatibility: there are many edge cases, like absorbing an empty array.
  * We cross-test against:
- * - https://github.com/ProvableHQ/snarkVM/tree/staging/algorithms
- * - https://github.com/arkworks-rs/crypto-primitives/tree/main
+ * - {@link https://github.com/ProvableHQ/snarkVM/tree/staging/algorithms | snarkVM algorithms}
+ * - {@link https://github.com/arkworks-rs/crypto-primitives/tree/main | arkworks crypto-primitives}
+ * @param opts - Sponge options. See {@link PoseidonSpongeOpts}.
+ * @returns Factory for sponge instances.
+ * @throws If the sponge dimensions or backing permutation options are invalid. {@link Error}
+ * @example
+ * Use the sponge helper to absorb several field elements and squeeze one digest.
+ *
+ * ```ts
+ * import { grainGenConstants, poseidonSponge } from '@noble/curves/abstract/poseidon.js';
+ * import { Field } from '@noble/curves/abstract/modular.js';
+ * const Fp = Field(17n);
+ * const constants = grainGenConstants({ Fp, t: 2, roundsFull: 8, roundsPartial: 8 });
+ * const makeSponge = poseidonSponge({
+ *   ...constants,
+ *   Fp,
+ *   rate: 1,
+ *   capacity: 1,
+ *   roundsFull: 8,
+ *   roundsPartial: 8,
+ *   sboxPower: 3,
+ * });
+ * const sponge = makeSponge();
+ * sponge.absorb([1n]);
+ * const out = sponge.squeeze(1);
+ * ```
  */
-export function poseidonSponge(opts: PoseidonSpongeOpts): () => PoseidonSponge {
-  for (const k of ['rate', 'capacity'] as const) asafenumber(opts[k], k);
+export function poseidonSponge(opts: TArg<PoseidonSpongeOpts>): TRet<() => PoseidonSponge> {
   const { rate, capacity } = opts;
-  const t = opts.rate + opts.capacity;
-  // Re-use hash instance between multiple instances
+  const t = spongeShape(rate, capacity);
+  // Re-use one hash instance between sponge instances; isolation depends on
+  // poseidon(...) itself staying immutable and not carrying mutable call state.
   const hash = poseidon({ ...opts, t });
   const { Fp } = opts;
-  return () => new PoseidonSponge(Fp, rate, capacity, hash);
+  return (() => new PoseidonSponge(Fp, rate, capacity, hash)) as TRet<() => PoseidonSponge>;
 }