@umbra-privacy/sdk 1.0.0 → 2.0.0

package/dist/math/index.d.cts

@@ -0,0 +1,1327 @@
+import { c as ModuloAddFunction, M as ModuloInvFunction, j as ModuloMulFunction, k as ModuloNegFunction, b as ModuloSubFunction, U as U512BasedBn254FieldElementSamplerFunction, l as U512BasedBn254FieldElementSamplerDeps, a as U512BasedCurve25519FieldElementSamplerFunction, e as Curve25519ModuloAddFunction, f as Curve25519ModuloInvFunction, g as Curve25519ModuloMulFunction, h as Curve25519ModuloPowFunction, i as Curve25519ModuloSubFunction, m as U512BasedCurve25519FieldElementSamplerDeps } from '../interfaces-D2NO6kDD.cjs';
+import { B as Bn254FieldElement } from '../types-BohhvPth.cjs';
+import { a as Base85Limb } from '../types-PwNLi_2k.cjs';
+import '../types-C_V_CaKK.cjs';
+
+/**
+ * BN254 Field Operations Module
+ *
+ * This module provides higher-level arithmetic operations over the BN254 scalar
+ * field F_r, including modular exponentiation, multiplicative inverse computation,
+ * and the basic field operations (add, subtract, multiply). These functions build
+ * on the branded type system defined in `types.ts` and are intended for use in
+ * cryptographic protocols such as Groth16 proof generation, Fiat-Shamir challenges,
+ * and ZK circuit witness computation.
+ *
+ * @remarks
+ * ## BN254 and the Scalar Field
+ *
+ * The BN254 curve (also known as alt_bn128 or bn256) is a pairing-friendly
+ * elliptic curve whose scalar field has prime order:
+ * ```
+ * r = 21888242871839275222246405745257275088548364400416034343698204186575808495617
+ * ```
+ * All operations in this module reduce their results modulo `r`, ensuring that
+ * outputs are always valid field elements in the range `[0, r-1]`.
+ *
+ * ## Performance Characteristics
+ *
+ * - `bn254Add`, `bn254Sub`, `bn254Mul`: O(1) — single BigInt operation + reduction
+ * - `bn254ModuloPow`: O(log exp) squarings and multiplications via square-and-multiply
+ * - `computeBn254ModularInverse`: O(log p) — Fermat exponentiation with p-2 as exponent
+ * - `computeBn254LimbwiseSumInverse`: O(log p) — three additions followed by inversion
+ *
+ * ## Security Note
+ *
+ * The inverse functions use Fermat's Little Theorem (`a^(p-2) mod p`) rather than
+ * the Extended Euclidean Algorithm. This choice trades a small performance overhead
+ * for a simpler, more auditable implementation. The underlying `modulePow` helper
+ * is intentionally non-constant-time (uses the `bigint` `%` operator internally);
+ * for constant-time arithmetic, use the functions in `field-arithmetic.ts`.
+ *
+ * @see {@link ./field-arithmetic} Constant-time field arithmetic
+ * @see {@link ./types} BN254 field element types and validation
+ *
+ * @packageDocumentation
+ * @module math/bn254/operations
+ */
+
+/**
+ * Computes the multiplicative inverse of a BN254 field element using
+ * Fermat's Little Theorem.
+ *
+ * @remarks
+ * ## Mathematical Background
+ *
+ * For a prime field F_p, every non-zero element `a` has a unique multiplicative
+ * inverse `a^(-1)` satisfying:
+ * ```
+ * a * a^(-1) ≡ 1  (mod p)
+ * ```
+ *
+ * By Fermat's Little Theorem, for prime `p` and `a != 0 (mod p)`:
+ * ```
+ * a^(p-1) ≡ 1  (mod p)
+ * ```
+ * Multiplying both sides by `a^(-1)`:
+ * ```
+ * a^(p-2) ≡ a^(-1)  (mod p)
+ * ```
+ *
+ * This function evaluates `a^(p-2) mod p` via the square-and-multiply algorithm
+ * in O(log p) field multiplications (approximately 254 squarings for BN254).
+ *
+ * ## Input Normalization
+ *
+ * The input is first normalized to its canonical representative in `[0, p-1]`
+ * via double reduction. If the normalized value is `0n`, there is no inverse and
+ * a `CryptographyError` is thrown.
+ *
+ * ## Complexity
+ *
+ * O(log p) ≈ O(254) field multiplications (squarings and multiplications via
+ * the square-and-multiply algorithm on a 254-bit exponent `p-2`).
+ *
+ * @param value - The BN254 field element to invert. Must be non-zero in the field.
+ * @returns The multiplicative inverse of `value` in `[1, BN254_FIELD_PRIME - 1]`.
+ *
+ * @throws {CryptographyError} If `value` is congruent to zero modulo the field prime,
+ *   because zero has no multiplicative inverse in any field.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   computeBn254ModularInverse,
+ *   bn254Mul,
+ *   BN254_FIELD_PRIME,
+ * } from "@umbra/sdk";
+ * import { assertBn254FieldElement } from "@umbra/sdk";
+ *
+ * const a = 12345n;
+ * assertBn254FieldElement(a, "a");
+ *
+ * const aInv = computeBn254ModularInverse(a);
+ *
+ * // Verify: a * a^(-1) = 1 (mod p)
+ * const product = bn254Mul(a, aInv);
+ * console.log(product === 1n); // true
+ *
+ * // Division by a: b / a = b * a^(-1) mod p
+ * const b = 99999n;
+ * assertBn254FieldElement(b, "b");
+ * const quotient = bn254Mul(b, aInv); // b / a mod p
+ * ```
+ *
+ * @see {@link bn254ModuloPow} For general modular exponentiation in the BN254 field
+ * @see {@link computeBn254LimbwiseSumInverse} For the inverse of a Base85 limb sum
+ *
+ * @public
+ */
+declare function computeBn254ModularInverse(value: Bn254FieldElement): Bn254FieldElement;
+/**
+ * Computes the multiplicative inverse of the sum of three Base85 limbs in the
+ * BN254 scalar field.
+ *
+ * @remarks
+ * ## Context: Base85 Limb Representation
+ *
+ * In ZK circuits that use the Circom/Groth16 toolchain, 255-bit field element
+ * inputs are commonly represented as three 85-bit limbs (sometimes called
+ * "Base85 limbs") to allow efficient constraint generation. Each limb holds
+ * a 85-bit chunk of the full value:
+ * ```
+ * full_value = limbs[0] + limbs[1] * 2^85 + limbs[2] * 2^170
+ * ```
+ *
+ * ## Circuit Non-Zero Validation
+ *
+ * Proving that a value is non-zero in a ZK circuit requires the circuit to
+ * supply the multiplicative inverse of that value as an auxiliary witness.
+ * When the value is represented in limbwise form, the circuit sometimes needs
+ * the inverse of the *sum of the limbs* rather than the inverse of the
+ * reconstructed value. This function computes exactly that:
+ * ```
+ * sum = (limbs[0] + limbs[1] + limbs[2]) mod p
+ * result = sum^(-1) mod p
+ * ```
+ *
+ * ## Why Limbwise Sum Instead of Reconstructed Value?
+ *
+ * The sum `limbs[0] + limbs[1] + limbs[2]` is a cheaper operation in
+ * the circuit compared to the full positional reconstruction
+ * `limbs[0] + limbs[1]*2^85 + limbs[2]*2^170`. The sum-based non-zero check
+ * works because if all three limbs are zero, their sum is also zero; otherwise
+ * the sum is guaranteed to be non-zero (given the limb range constraints enforced
+ * by the circuit).
+ *
+ * @param limbs - A tuple of three `Base85Limb` values: `[low, middle, high]`.
+ *   Each limb must be in the range `[0, 2^85 - 1]`.
+ * @returns The multiplicative inverse of `(limbs[0] + limbs[1] + limbs[2]) mod p`
+ *   as a `Bn254FieldElement` in the range `[1, BN254_FIELD_PRIME - 1]`.
+ *
+ * @throws {CryptographyError} If the sum of all three limbs is congruent to zero
+ *   modulo the BN254 field prime, meaning no inverse exists.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   computeBn254LimbwiseSumInverse,
+ *   BN254_FIELD_PRIME,
+ * } from "@umbra/sdk";
+ * import { assertBase85Limb } from "@umbra/sdk";
+ *
+ * const low  = 0x1234n;
+ * const mid  = 0x5678n;
+ * const high = 0x9ABCn;
+ * assertBase85Limb(low,  "low");
+ * assertBase85Limb(mid,  "mid");
+ * assertBase85Limb(high, "high");
+ *
+ * const inverse = computeBn254LimbwiseSumInverse([low, mid, high]);
+ *
+ * // Verify: (low + mid + high) * inverse ≡ 1 (mod p)
+ * const sum = (low + mid + high) % BN254_FIELD_PRIME;
+ * const check = (sum * inverse) % BN254_FIELD_PRIME;
+ * console.log(check === 1n); // true
+ * ```
+ *
+ * @see {@link computeBn254ModularInverse} For inverting a single field element
+ * @see {@link Base85Limb} The branded limb type from `crypto/poseidon/types`
+ *
+ * @public
+ */
+declare function computeBn254LimbwiseSumInverse(limbs: [Base85Limb, Base85Limb, Base85Limb]): Bn254FieldElement;
+/**
+ * Computes modular exponentiation in the BN254 scalar field: `base^exp mod p`.
+ *
+ * @remarks
+ * This is a type-safe wrapper around the internal `modulePow` helper that
+ * constrains both the input and output to the BN254 scalar field. It delegates
+ * to the square-and-multiply algorithm with O(log exp) multiplications.
+ *
+ * ## Typical Use Cases
+ *
+ * - Computing powers of a Fiat-Shamir challenge scalar
+ * - Evaluating polynomial commitments at a challenge point
+ * - Batch inversion via exponentiation (less efficient than Extended GCD but simpler)
+ *
+ * ## Exponent Sign
+ *
+ * The exponent must be a non-negative `bigint`. Negative exponents are not supported;
+ * use `computeBn254ModularInverse` for `base^(-1)` and compose with `bn254ModuloPow`
+ * for general negative powers.
+ *
+ * @param base - The base field element in `[0, BN254_FIELD_PRIME - 1]`.
+ * @param exp - The non-negative integer exponent (a plain `bigint`, not necessarily in the field).
+ * @returns `base^exp mod BN254_FIELD_PRIME` as a `Bn254FieldElement`.
+ *
+ * @example
+ * ```typescript
+ * import { bn254ModuloPow, assertBn254FieldElement } from "@umbra/sdk";
+ *
+ * const challenge = 999n;
+ * assertBn254FieldElement(challenge, "challenge");
+ *
+ * // Compute challenge^3 mod p (evaluating a cubic polynomial coefficient)
+ * const cubed = bn254ModuloPow(challenge, 3n);
+ *
+ * // Compute challenge^0 = 1 (identity)
+ * const identity = bn254ModuloPow(challenge, 0n);
+ * console.log(identity === 1n); // true
+ * ```
+ *
+ * @see {@link computeBn254ModularInverse} For the special case exp = -1
+ * @see {@link bn254Mul} For a single multiplication
+ *
+ * @public
+ */
+declare function bn254ModuloPow(base: Bn254FieldElement, exp: bigint): Bn254FieldElement;
+/**
+ * Computes the sum of two BN254 scalar field elements modulo the field prime.
+ *
+ * @remarks
+ * ## Formula
+ *
+ * ```
+ * result = (a + b) mod BN254_FIELD_PRIME
+ * ```
+ *
+ * Because both `a` and `b` are in `[0, p-1]`, their sum is in `[0, 2p-2]`,
+ * which requires at most one modular reduction step. This is implemented directly
+ * via JavaScript's `%` operator on `bigint`.
+ *
+ * ## Overflow Behavior
+ *
+ * JavaScript `bigint` arithmetic is arbitrary precision, so there is no risk of
+ * overflow. The modular reduction always yields a result in `[0, p-1]`.
+ *
+ * @param a - First summand, a valid BN254 field element in `[0, BN254_FIELD_PRIME - 1]`.
+ * @param b - Second summand, a valid BN254 field element in `[0, BN254_FIELD_PRIME - 1]`.
+ * @returns `(a + b) mod BN254_FIELD_PRIME` as a `Bn254FieldElement`.
+ *
+ * @example
+ * ```typescript
+ * import { bn254Add, assertBn254FieldElement, BN254_FIELD_PRIME } from "@umbra/sdk";
+ *
+ * const a = 10n;
+ * const b = 20n;
+ * assertBn254FieldElement(a, "a");
+ * assertBn254FieldElement(b, "b");
+ *
+ * const sum = bn254Add(a, b);
+ * console.log(sum === 30n); // true
+ *
+ * // Demonstrates wraparound at the field boundary
+ * const nearPrime = BN254_FIELD_PRIME - 1n;
+ * assertBn254FieldElement(nearPrime, "nearPrime");
+ * const wrapped = bn254Add(nearPrime, b);
+ * // (p - 1 + 20) mod p = 19
+ * console.log(wrapped === 19n); // true
+ * ```
+ *
+ * @see {@link bn254Sub} For modular subtraction
+ * @see {@link bn254Mul} For modular multiplication
+ *
+ * @public
+ */
+declare function bn254Add(a: Bn254FieldElement, b: Bn254FieldElement): Bn254FieldElement;
+/**
+ * Computes the difference of two BN254 scalar field elements modulo the field prime.
+ *
+ * @remarks
+ * ## Formula
+ *
+ * ```
+ * result = (a - b) mod BN254_FIELD_PRIME
+ * ```
+ *
+ * Because `a - b` can be negative when `b > a`, the result is obtained by
+ * adding the prime before taking the modulo to ensure canonicalization into
+ * `[0, p-1]`:
+ * ```
+ * diff = a - b
+ * result = ((diff % p) + p) % p
+ * ```
+ *
+ * This pattern handles both the case where `a >= b` (no wrap-around needed)
+ * and the case where `a < b` (wrap-around by adding `p`).
+ *
+ * @param a - Minuend, a valid BN254 field element in `[0, BN254_FIELD_PRIME - 1]`.
+ * @param b - Subtrahend, a valid BN254 field element in `[0, BN254_FIELD_PRIME - 1]`.
+ * @returns `(a - b) mod BN254_FIELD_PRIME` as a `Bn254FieldElement` in `[0, p-1]`.
+ *
+ * @example
+ * ```typescript
+ * import { bn254Sub, assertBn254FieldElement, BN254_FIELD_PRIME } from "@umbra/sdk";
+ *
+ * const a = 30n;
+ * const b = 10n;
+ * assertBn254FieldElement(a, "a");
+ * assertBn254FieldElement(b, "b");
+ *
+ * const diff = bn254Sub(a, b);
+ * console.log(diff === 20n); // true
+ *
+ * // Underflow wraps around the field prime
+ * const small = 5n;
+ * assertBn254FieldElement(small, "small");
+ * const wrapped = bn254Sub(small, b);
+ * // (5 - 10 + p) mod p = p - 5
+ * console.log(wrapped === BN254_FIELD_PRIME - 5n); // true
+ * ```
+ *
+ * @see {@link bn254Add} For modular addition
+ * @see {@link bn254Mul} For modular multiplication
+ *
+ * @public
+ */
+declare function bn254Sub(a: Bn254FieldElement, b: Bn254FieldElement): Bn254FieldElement;
+/**
+ * Computes the product of two BN254 scalar field elements modulo the field prime.
+ *
+ * @remarks
+ * ## Formula
+ *
+ * ```
+ * result = (a * b) mod BN254_FIELD_PRIME
+ * ```
+ *
+ * Because both `a` and `b` are approximately 254-bit values, their product is
+ * approximately 508 bits before reduction. JavaScript's `bigint` type handles
+ * arbitrary precision arithmetic natively, so no overflow occurs. The result
+ * is reduced to `[0, p-1]` via a single `%` operation.
+ *
+ * ## Performance Note
+ *
+ * This function uses JavaScript's built-in `bigint` multiplication, which is not
+ * constant-time. For cryptographic contexts where timing side-channels are a
+ * concern (e.g., secret-key operations), use `bn254ModuloMul` from
+ * `field-arithmetic.ts` which uses constant-time Montgomery multiplication.
+ *
+ * @param a - First factor, a valid BN254 field element in `[0, BN254_FIELD_PRIME - 1]`.
+ * @param b - Second factor, a valid BN254 field element in `[0, BN254_FIELD_PRIME - 1]`.
+ * @returns `(a * b) mod BN254_FIELD_PRIME` as a `Bn254FieldElement`.
+ *
+ * @example
+ * ```typescript
+ * import { bn254Mul, assertBn254FieldElement, BN254_FIELD_PRIME } from "@umbra/sdk";
+ *
+ * const a = 7n;
+ * const b = 8n;
+ * assertBn254FieldElement(a, "a");
+ * assertBn254FieldElement(b, "b");
+ *
+ * const product = bn254Mul(a, b);
+ * console.log(product === 56n); // true
+ *
+ * // Product of two large field elements wraps around
+ * const large = BN254_FIELD_PRIME - 1n;
+ * assertBn254FieldElement(large, "large");
+ * const result = bn254Mul(large, 2n as unknown as typeof large);
+ * // (p - 1) * 2 mod p = p - 2
+ * console.log(result === BN254_FIELD_PRIME - 2n); // true
+ * ```
+ *
+ * @see {@link bn254Add} For modular addition
+ * @see {@link bn254Sub} For modular subtraction
+ * @see {@link computeBn254ModularInverse} For multiplicative inverse (division)
+ *
+ * @public
+ */
+declare function bn254Mul(a: Bn254FieldElement, b: Bn254FieldElement): Bn254FieldElement;
+
+/**
+ * BN254 Field Arithmetic — Constant-Time Montgomery Implementation
+ *
+ * This module provides the core constant-time modular arithmetic operations for
+ * the BN254 (alt_bn128) scalar prime field F_r. It is the cryptographic foundation
+ * of the BN254 math layer and implements all five field operations:
+ *
+ * - Addition: `(a + b) mod p`
+ * - Subtraction: `(a - b) mod p`
+ * - Multiplication: `(a * b) mod p` (via Montgomery multiplication)
+ * - Negation: `-a mod p`
+ * - Multiplicative inverse: `a^(-1) mod p` (via Fermat + Montgomery exponentiation)
+ *
+ * Additionally, it exports getter functions that return stable cached instances of
+ * each operation, and a utility for computing the modular inverse of a Base85 limb sum.
+ *
+ * @remarks
+ * ## BN254 Scalar Field
+ *
+ * The BN254 elliptic curve (also called alt_bn128 in the Ethereum context) has a
+ * cyclic group of prime order:
+ * ```
+ * p = 21888242871839275222246405745257275088548364400416034343698204186575808495617
+ *   = 0x30644e72e131a029b85045b68181585d2833e84879b9709143e1f593f0000001
+ * ```
+ * This prime has approximately 254 significant bits. Every arithmetic operation in
+ * Circom circuits, Groth16 proofs, and Poseidon hashes works modulo `p`.
+ *
+ * ## Constant-Time Design
+ *
+ * These implementations target *constant-operation-count* behavior, which is the
+ * achievable standard in JavaScript:
+ * - No data-dependent branching on secret values
+ * - All 4 limbs are always processed uniformly
+ * - Conditional selection uses bitwise masking (`ctSelect`)
+ * - Montgomery multiplication processes all iterations unconditionally
+ *
+ * True hardware-level constant time (immune to microarchitectural attacks such as
+ * cache-timing, branch prediction, and power analysis) is not achievable in JavaScript
+ * due to the JIT compiler and BigInt internals. However, this implementation avoids
+ * the most obvious timing leaks.
+ *
+ * ## 4-Limb (64-bit) Representation
+ *
+ * Values are stored as `[limb0, limb1, limb2, limb3]` in little-endian order:
+ * - `limb0`: bits 0–63 (least significant)
+ * - `limb1`: bits 64–127
+ * - `limb2`: bits 128–191
+ * - `limb3`: bits 192–255 (most significant)
+ *
+ * The reconstruction formula is:
+ * ```
+ * value = limb0 + limb1 * 2^64 + limb2 * 2^128 + limb3 * 2^192
+ * ```
+ *
+ * ## Montgomery Multiplication
+ *
+ * Multiplication uses the CIOS (Coarsely Integrated Operand Scanning) variant of
+ * Montgomery multiplication. Working in "Montgomery domain" (where each value `a`
+ * is stored as `aR mod p` for `R = 2^256`) allows the inner multiplication-and-reduction
+ * loop to avoid a full division by `p`. Instead, it uses a precomputed constant
+ * `p' = -p^(-1) mod 2^64` to make each output limb divisible by `2^64`, enabling
+ * a right-shift instead of a division.
+ *
+ * @see {@link ./types} BN254 field element types and validation
+ * @see {@link ./operations} Higher-level field operations (non-constant-time)
+ * @see {@link ./interfaces} Function type interfaces implemented here
+ * @see {@link ./field-element-sampler} Sampler that depends on this module
+ *
+ * @packageDocumentation
+ * @module math/bn254/field-arithmetic
+ */
+
+/**
+ * Returns a stable, cached reference to the BN254 constant-time modular addition function.
+ *
+ * @remarks
+ * This getter exists to enable patterns where a function reference is stored once
+ * and passed around by reference (e.g., stored in a closure, passed as a dependency,
+ * or compared by identity). Every call returns the same `ModuloAddFunction` instance,
+ * avoiding unnecessary object allocation.
+ *
+ * Internally uses nullish coalescing assignment (`??=`) for lazy initialization:
+ * the cached value is set on the first call and reused on all subsequent calls.
+ *
+ * @returns The singleton `bn254ModuloAdd` function instance.
+ *
+ * @example
+ * ```typescript
+ * import { getBn254ModularAdder } from "@umbra/sdk";
+ *
+ * const modAdd = getBn254ModularAdder();
+ *
+ * // Use as a named function
+ * const sum = modAdd(10n, 20n); // 30n
+ *
+ * // Same instance on every call — useful for referential equality checks
+ * const modAdd2 = getBn254ModularAdder();
+ * console.log(modAdd === modAdd2); // true
+ *
+ * // Pass as a dependency
+ * const sampler = getBn254FieldElementSampler({ modAdd });
+ * ```
+ *
+ * @see {@link bn254ModuloAdd} The underlying function
+ *
+ * @public
+ */
+declare function getBn254ModularAdder(): ModuloAddFunction;
+/**
+ * Returns a stable, cached reference to the BN254 constant-time modular subtraction function.
+ *
+ * @remarks
+ * Uses the same lazy-initialization pattern as `getBn254ModularAdder`. Returns the
+ * same `bn254ModuloSub` instance on every call, enabling referential equality checks
+ * and efficient dependency injection.
+ *
+ * @returns The singleton `bn254ModuloSub` function instance.
+ *
+ * @example
+ * ```typescript
+ * import { getBn254ModularSubtractor } from "@umbra/sdk";
+ *
+ * const modSub = getBn254ModularSubtractor();
+ * const diff = modSub(30n, 10n); // 20n
+ *
+ * // Referential equality guaranteed
+ * const modSub2 = getBn254ModularSubtractor();
+ * console.log(modSub === modSub2); // true
+ * ```
+ *
+ * @see {@link bn254ModuloSub} The underlying function
+ *
+ * @public
+ */
+declare function getBn254ModularSubtractor(): ModuloSubFunction;
+/**
+ * Returns a stable, cached reference to the BN254 constant-time modular multiplication function.
+ *
+ * @remarks
+ * Uses the same lazy-initialization pattern as `getBn254ModularAdder`. Returns the
+ * same `bn254ModuloMul` instance on every call. The underlying function uses
+ * Montgomery multiplication internally.
+ *
+ * @returns The singleton `bn254ModuloMul` function instance.
+ *
+ * @example
+ * ```typescript
+ * import { getBn254ModularMultiplier } from "@umbra/sdk";
+ *
+ * const modMul = getBn254ModularMultiplier();
+ * const product = modMul(7n, 8n); // 56n
+ *
+ * // Referential equality guaranteed
+ * const modMul2 = getBn254ModularMultiplier();
+ * console.log(modMul === modMul2); // true
+ *
+ * // Pass as a dependency to the sampler
+ * const sampler = getBn254FieldElementSampler({ modMul });
+ * ```
+ *
+ * @see {@link bn254ModuloMul} The underlying Montgomery multiplication function
+ *
+ * @public
+ */
+declare function getBn254ModularMultiplier(): ModuloMulFunction;
+/**
+ * Returns a stable, cached reference to the BN254 constant-time modular negation function.
+ *
+ * @remarks
+ * Uses the same lazy-initialization pattern as `getBn254ModularAdder`. Returns the
+ * same `bn254ModuloNeg` instance on every call.
+ *
+ * @returns The singleton `bn254ModuloNeg` function instance.
+ *
+ * @example
+ * ```typescript
+ * import { getBn254ModularNegator, getBn254ModularAdder } from "@umbra/sdk";
+ *
+ * const modNeg = getBn254ModularNegator();
+ * const negated = modNeg(10n); // BN254_FIELD_PRIME - 10n
+ *
+ * // Verify: 10 + (-10) = 0
+ * const modAdd = getBn254ModularAdder();
+ * console.log(modAdd(10n, negated) === 0n); // true
+ *
+ * // Referential equality guaranteed
+ * const modNeg2 = getBn254ModularNegator();
+ * console.log(modNeg === modNeg2); // true
+ * ```
+ *
+ * @see {@link bn254ModuloNeg} The underlying function
+ *
+ * @public
+ */
+declare function getBn254ModularNegator(): ModuloNegFunction;
+/**
+ * Returns a stable, cached reference to the BN254 modular multiplicative inverse function.
+ *
+ * @remarks
+ * Uses the same lazy-initialization pattern as `getBn254ModularAdder`. Returns the
+ * same `bn254ModuloInv` instance on every call. Note that `bn254ModuloInv` uses
+ * Fermat's Little Theorem with Montgomery exponentiation — it is significantly
+ * more expensive than addition, subtraction, or a single multiplication.
+ *
+ * @returns The singleton `bn254ModuloInv` function instance.
+ *
+ * @example
+ * ```typescript
+ * import { getBn254ModularInverter, getBn254ModularMultiplier } from "@umbra/sdk";
+ *
+ * const modInv = getBn254ModularInverter();
+ * const inverse = modInv(7n);
+ *
+ * // Verify: 7 * 7^(-1) = 1
+ * const modMul = getBn254ModularMultiplier();
+ * console.log(modMul(7n, inverse) === 1n); // true
+ *
+ * // Referential equality guaranteed
+ * const modInv2 = getBn254ModularInverter();
+ * console.log(modInv === modInv2); // true
+ * ```
+ *
+ * @see {@link bn254ModuloInv} The underlying Fermat-based inversion function
+ *
+ * @public
+ */
+declare function getBn254ModularInverter(): ModuloInvFunction;
+
+/**
+ * BN254 Field Element Sampler Implementation
+ *
+ * This module provides a constant-time implementation for sampling BN254 scalar
+ * field elements from 512-bit big-endian byte arrays. The primary use case is
+ * deriving field elements from hash outputs (e.g., SHA-512, Keccak-512) or from
+ * concatenated CSPRNG outputs, as required by Fiat-Shamir transformations and
+ * key derivation in ZK proof systems.
+ *
+ * @remarks
+ * ## Why 512 Bits?
+ *
+ * The BN254 scalar field prime `p` is approximately `2^254`. If a 256-bit
+ * random value were mapped directly into the field via `value mod p`, there would
+ * be a statistical bias: the values in `[0, 2^256 mod p - 1]` would appear with
+ * probability `2/(floor(2^256 / p) + 1)`, while higher values appear with
+ * probability `1/(floor(2^256 / p) + 1)`. This bias is approximately `2^(-127)`,
+ * which is borderline for cryptographic applications.
+ *
+ * Using a 512-bit input reduces the maximum bias to approximately `2^(-254)`,
+ * which is cryptographically negligible for any practical security level.
+ *
+ * ## Algorithm
+ *
+ * Given a 512-bit big-endian input `h`, the module:
+ * 1. Splits `h` into two 256-bit halves (`high = h[0..31]`, `low = h[32..63]`)
+ * 2. Reduces both halves to `[0, p)` using constant-time trial subtraction (`reduce256`)
+ * 3. Computes `result = (high * R + low) mod p` where `R = 2^256 mod p`
+ *    (the Montgomery constant for converting from 512-bit to field element)
+ *
+ * This is equivalent to interpreting the 512-bit value as an integer and reducing
+ * it modulo `p` in a constant-time manner.
+ *
+ * ## Constant-Time Guarantees
+ *
+ * All internal operations are constant-operation-count:
+ * - `ctSelect`: bitwise masking instead of branching
+ * - `bigintToLimbs` / `limbsToBigint`: fixed 4-limb operations
+ * - `conditionalSubtractP`: always subtracts and always selects (via mask)
+ * - `reduce256`: exactly 5 conditional subtractions, no early exit
+ *
+ * True hardware-level constant time cannot be guaranteed in JavaScript due to JIT
+ * compilation and BigInt internals, but the implementation avoids all data-dependent
+ * control flow.
+ *
+ * @see {@link ./interfaces.U512BasedBn254FieldElementSamplerFunction} Interface type
+ * @see {@link ./interfaces.U512BasedBn254FieldElementSamplerDeps} Dependency injection type
+ * @see {@link ./field-arithmetic} The constant-time modular arithmetic layer
+ *
+ * @packageDocumentation
+ * @module math/bn254/field-element-sampler
+ */
+
+/**
+ * Creates a factory-configured U512-based BN254 field element sampler.
+ *
+ * Returns a closure that accepts a 64-byte big-endian byte array (`U512BeBytes`)
+ * and produces a uniformly distributed element of the BN254 scalar field.
+ *
+ * @param deps - Optional dependency injection for custom modular arithmetic.
+ *   When omitted, uses the production constant-time implementations from
+ *   `field-arithmetic.ts` (`bn254ModuloAdd` and `bn254ModuloMul`).
+ * @returns A `U512BasedBn254FieldElementSamplerFunction` closure bound to the
+ *   provided (or default) arithmetic functions.
+ *
+ * @remarks
+ * ## Algorithm
+ *
+ * The returned sampler function, when invoked with a 64-byte input `h`:
+ *
+ * 1. **Split**: reads `high = h[0..31]` and `low = h[32..63]` as big-endian integers.
+ * 2. **Reduce**: calls `reduce256(high)` and `reduce256(low)` to bring both halves
+ *    into `[0, p-1]` using constant-time trial subtraction.
+ * 3. **Combine**: computes `result = modMul(highReduced, R) + modAdd(lowReduced)`
+ *    — i.e., `(high * R + low) mod p` — where `R = 2^256 mod p`.
+ *
+ * This is mathematically equivalent to:
+ * ```
+ * result = (h interpreted as a 512-bit big-endian integer) mod p
+ * ```
+ *
+ * ## Dependency Injection
+ *
+ * The `opts.modAdd` and `opts.modMul` overrides are applied to the final combine
+ * step (step 3). The `reduce256` step always uses the internal constant-time
+ * `conditionalSubtractP` regardless of injection. This design ensures that
+ * tests can substitute the combine arithmetic while keeping the reduction step
+ * deterministic.
+ *
+ * @example
+ * ```typescript
+ * import { getBn254FieldElementSampler } from "@umbra/sdk";
+ *
+ * // Default constant-time arithmetic
+ * const sampler = getBn254FieldElementSampler();
+ * const fieldElement = sampler(someU512Input);
+ *
+ * // Custom arithmetic for testing
+ * const testSampler = getBn254FieldElementSampler({
+ *   modAdd: (a, b) => (a + b) % BN254_FIELD_PRIME,
+ *   modMul: (a, b) => (a * b) % BN254_FIELD_PRIME,
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Deriving a field element from two concatenated SHA-256 hashes
+ * const hash1 = sha256(someData);        // 32 bytes
+ * const hash2 = sha256(someOtherData);   // 32 bytes
+ * const combined = new Uint8Array(64);
+ * combined.set(hash1, 0);
+ * combined.set(hash2, 32);
+ * assertU512BeBytes(combined);
+ *
+ * const sampler = getBn254FieldElementSampler();
+ * const fieldElement = sampler(combined);
+ * // fieldElement is a well-distributed BN254 field element derived from the hashes
+ * ```
+ *
+ * @see {@link bn254FieldElementSampler} Pre-instantiated default sampler
+ * @see {@link U512BasedBn254FieldElementSamplerDeps} Dependency injection interface
+ * @see {@link U512BasedBn254FieldElementSamplerFunction} The returned function type
+ *
+ * @public
+ */
+declare function getBn254FieldElementSampler(deps?: U512BasedBn254FieldElementSamplerDeps): U512BasedBn254FieldElementSamplerFunction;
+/**
+ * The pre-instantiated default U512-based BN254 field element sampler.
+ *
+ * This is a convenience export of `getBn254FieldElementSampler()` with
+ * no arguments — using the default constant-time `bn254ModuloAdd` and
+ * `bn254ModuloMul` implementations from `field-arithmetic.ts`.
+ *
+ * @remarks
+ * Use this export directly when you do not need to inject custom arithmetic.
+ * It avoids the overhead of calling the factory function on every use.
+ *
+ * The sampler is stateless (it is a pure function of its input), so sharing this
+ * instance across multiple call sites is safe.
+ *
+ * @example
+ * ```typescript
+ * import { bn254FieldElementSampler } from "@umbra/sdk";
+ *
+ * // Produce a field element from a 64-byte CSPRNG output
+ * const randomBytes = crypto.getRandomValues(new Uint8Array(64));
+ * assertU512BeBytes(randomBytes);
+ * const fieldElement = bn254FieldElementSampler(randomBytes);
+ * // fieldElement is a uniformly distributed BN254 scalar field element
+ * ```
+ *
+ * @see {@link getBn254FieldElementSampler} The factory for custom configurations
+ * @see {@link U512BasedBn254FieldElementSamplerFunction} The function type
+ *
+ * @public
+ */
+declare const bn254FieldElementSampler: U512BasedBn254FieldElementSamplerFunction;
+
+/**
+ * Curve25519 Base Field Arithmetic — Concrete Implementation
+ *
+ * This module provides the constant-operation-count implementations of all
+ * modular arithmetic operations over the Curve25519 prime field GF(p), where:
+ * ```
+ * p = 2^255 - 19
+ *   = 57896044618658097711785492504343953926634992332820282019728792003956564819949
+ * ```
+ *
+ * ## Role in the SDK
+ *
+ * This module is the lowest-level arithmetic layer in the SDK's cryptographic
+ * stack. Its exported functions are consumed by:
+ *
+ * - **`crypto/rescue-cipher/`** — the Rescue-XLIX block cipher used inside
+ *   Arcium MPC computations for symmetric encryption of Umbra confidential
+ *   token account balances.
+ * - **`math/curve25519/interfaces`** — the function-type contracts that the
+ *   exported symbols satisfy.
+ * - Dependency-injection consumers that call
+ *   `getCurve25519FieldElementSampler` with custom arithmetic.
+ *
+ * X25519 key-exchange itself (used for Umbra encrypted token account key
+ * registration) does not call this module directly — its scalar multiplication
+ * is handled by `@noble/curves` — but the field prime is the same.
+ *
+ * ## Algorithm Overview
+ *
+ * ### Addition / Subtraction
+ *
+ * Both operations are implemented at the 4-limb level using carry/borrow
+ * propagation, followed by a **constant-time conditional correction**:
+ *
+ * - **Addition**: compute `t = a + b`; if `t ≥ p` then return `t - p`, else `t`.
+ *   The conditional is resolved by a bitwise mask derived from the carry and
+ *   borrow, never an `if` statement.
+ * - **Subtraction**: compute `d = a - b`; if a borrow occurred (a < b), add `p`
+ *   back. The borrow bit is propagated as a mask applied to `P_LIMBS`.
+ *
+ * ### Multiplication
+ *
+ * Uses JavaScript's native `BigInt` multiplication (`a * b`) followed by
+ * a single `% p` reduction. While this is not a limb-level schoolbook
+ * implementation, `BigInt` intermediate values of ≤ 510 bits keep the
+ * per-call work uniform. Montgomery form is not used because the constant
+ * conversion overhead is not amortised over the small number of multiplications
+ * per Rescue-XLIX round.
+ *
+ * ### Inversion
+ *
+ * Uses Fermat's Little Theorem: `a^(-1) ≡ a^(p-2) (mod p)`. This delegates to
+ * the square-and-multiply exponentiation function with a fixed exponent of
+ * p - 2 ≈ 2^255, costing ≈ 255 squarings and ~128 multiplications.
+ *
+ * ### Exponentiation
+ *
+ * Binary (square-and-multiply) exponentiation via `moduleExpLimbs`. The loop
+ * visits each bit of the exponent from LSB to MSB; the branch on the current
+ * bit (`exp & 1n`) operates on the **exponent**, not secret field data, so it
+ * does not constitute a secret-dependent branch.
+ *
+ * ## Security Considerations
+ *
+ * True hardware-level constant time cannot be guaranteed in JavaScript because
+ * the V8/SpiderMonkey JIT, branch predictors, and GC can all introduce
+ * data-dependent timing variation. These implementations are
+ * **constant-operation-count**: they always execute the same sequence of BigInt
+ * operations regardless of the input values. This is the accepted standard for
+ * JavaScript cryptographic libraries (e.g., `@noble/curves`).
+ *
+ * Secret-dependent branching is avoided by:
+ * - Using `ctSelect` (bitwise mask) for all conditional value choices.
+ * - Processing all 4 limbs in every loop iteration regardless of value.
+ * - Applying `P_LIMBS` correction via masking rather than a conditional add.
+ *
+ * ## Limb Representation
+ *
+ * All internal computation decomposes field elements into four 64-bit limbs
+ * stored in little-endian order `[limb0, limb1, limb2, limb3]`:
+ * ```
+ * value = limb0 + limb1×2^64 + limb2×2^128 + limb3×2^192
+ * ```
+ * - `limb0` — bits 0-63 (least significant)
+ * - `limb1` — bits 64-127
+ * - `limb2` — bits 128-191
+ * - `limb3` — bits 192-255 (most significant; high bit always 0 for valid elements)
+ *
+ * The 4-limb split keeps individual BigInt values at a uniform 64-bit size,
+ * making per-limb arithmetic cost independent of the field element's magnitude.
+ *
+ * @module implementation/mathematics/curve25519-field-arithmetic
+ * @packageDocumentation
+ */
+
+/**
+ * Constant-operation-count modular addition for the Curve25519 base field.
+ *
+ * @remarks
+ * Computes the canonical field sum:
+ * ```
+ * result ≡ a + b  (mod p),  p = 2^255 - 19
+ * ```
+ *
+ * Implementation delegates to {@link addModuleLimbs} which performs the
+ * addition and conditional reduction entirely with bitwise masking — no
+ * data-dependent branches on `a` or `b`.
+ *
+ * This function satisfies {@link Curve25519ModuloAddFunction}.
+ *
+ * @param a - First field element. Must be in canonical range [0, p-1].
+ * @param b - Second field element. Must be in canonical range [0, p-1].
+ * @returns `(a + b) mod p` in canonical range [0, p-1].
+ *
+ * @example
+ * ```typescript
+ * import { curve25519ModuloAdd, CURVE25519_FIELD_PRIME } from "@umbra-privacy/sdk";
+ *
+ * // Basic addition
+ * const sum = curve25519ModuloAdd(10n, 20n);
+ * console.log(sum); // 30n
+ *
+ * // Wrap-around: p-1 + 1 = 0
+ * const wrap = curve25519ModuloAdd(CURVE25519_FIELD_PRIME - 1n, 1n);
+ * console.log(wrap); // 0n
+ * ```
+ *
+ * @see {@link curve25519ModuloSub} — complementary subtraction
+ * @see {@link getCurve25519ModularAddFunction} — returns a cached reference to this function
+ *
+ * @public
+ */
+declare const curve25519ModuloAdd: Curve25519ModuloAddFunction;
+/**
+ * Constant-operation-count modular subtraction for the Curve25519 base field.
+ *
+ * @remarks
+ * Computes the canonical field difference:
+ * ```
+ * result ≡ a - b  (mod p),  p = 2^255 - 19
+ * ```
+ *
+ * When a < b the result wraps around: `a - b + p`, which is still in [0, p-1].
+ * Implementation delegates to {@link subModuleLimbs}, which adds p back via
+ * a borrow-derived bitmask rather than a conditional branch.
+ *
+ * This function satisfies {@link Curve25519ModuloSubFunction}.
+ *
+ * @param a - Minuend. Must be in canonical range [0, p-1].
+ * @param b - Subtrahend. Must be in canonical range [0, p-1].
+ * @returns `(a - b) mod p` in canonical range [0, p-1].
+ *
+ * @example
+ * ```typescript
+ * import { curve25519ModuloSub, CURVE25519_FIELD_PRIME } from "@umbra-privacy/sdk";
+ *
+ * // Normal subtraction
+ * const diff = curve25519ModuloSub(30n, 10n);
+ * console.log(diff); // 20n
+ *
+ * // Wrap-around: 0 - 1 = p - 1
+ * const wrap = curve25519ModuloSub(0n, 1n);
+ * console.log(wrap === CURVE25519_FIELD_PRIME - 1n); // true
+ * ```
+ *
+ * @see {@link curve25519ModuloAdd} — complementary addition
+ * @see {@link getCurve25519ModularSubFunction} — returns a cached reference to this function
+ *
+ * @public
+ */
+declare const curve25519ModuloSub: Curve25519ModuloSubFunction;
+/**
+ * Modular multiplication for the Curve25519 base field.
+ *
+ * @remarks
+ * Computes the canonical field product:
+ * ```
+ * result ≡ a × b  (mod p),  p = 2^255 - 19
+ * ```
+ *
+ * Implementation converts both operands to full-precision `BigInt`, multiplies
+ * natively (producing a ≤ 510-bit intermediate), then reduces with `% p`.
+ * See {@link mulModuleLimbs} for rationale on why Montgomery form is not used.
+ *
+ * This function satisfies {@link Curve25519ModuloMulFunction}.
+ *
+ * @param a - First factor. Must be in canonical range [0, p-1].
+ * @param b - Second factor. Must be in canonical range [0, p-1].
+ * @returns `(a × b) mod p` in canonical range [0, p-1].
+ *
+ * @example
+ * ```typescript
+ * import { curve25519ModuloMul, CURVE25519_FIELD_PRIME } from "@umbra-privacy/sdk";
+ *
+ * // Basic multiplication
+ * const product = curve25519ModuloMul(7n, 8n);
+ * console.log(product); // 56n
+ *
+ * // Large value reduces modulo p
+ * const large = curve25519ModuloMul(CURVE25519_FIELD_PRIME - 1n, 2n);
+ * // (p-1) × 2 = 2p - 2 ≡ p - 2 (mod p)
+ * console.log(large === CURVE25519_FIELD_PRIME - 2n); // true
+ * ```
+ *
+ * @see {@link curve25519ModuloInv} — uses this function for inversion via Fermat's theorem
+ * @see {@link getCurve25519ModularMulFunction} — returns a cached reference to this function
+ *
+ * @public
+ */
+declare const curve25519ModuloMul: Curve25519ModuloMulFunction;
+/**
+ * Modular multiplicative inverse for the Curve25519 base field.
+ *
+ * @remarks
+ * Computes the unique inverse such that:
+ * ```
+ * a × result ≡ 1  (mod p),  p = 2^255 - 19
+ * ```
+ *
+ * ## Algorithm — Fermat's Little Theorem
+ *
+ * Because p is prime, Fermat's Little Theorem guarantees:
+ * ```
+ * a^(p-1) ≡ 1  (mod p)  for all a ≠ 0
+ * ```
+ * Therefore:
+ * ```
+ * a^(-1) ≡ a^(p-2)  (mod p)
+ * ```
+ *
+ * The exponent p - 2 is a fixed protocol constant, so the square-and-multiply
+ * loop in {@link moduleExpLimbs} does not branch on secret data.
+ *
+ * **Cost**: ≈ 255 squarings + ≈ 128 multiplications. For applications that call
+ * inversion in a tight loop, a batch-inversion algorithm (Montgomery's trick)
+ * can reduce the cost to 1 inversion + 3(n-1) multiplications for n elements.
+ *
+ * This function satisfies {@link Curve25519ModuloInvFunction}.
+ *
+ * @param a - The field element to invert. Must be in range [1, p-1].
+ *   Passing `0n` is a programming error — zero has no multiplicative inverse.
+ * @returns The unique inverse `a^(-1) mod p` in range [1, p-1].
+ * @throws {Error} If `a === 0n`. The error message is
+ *   `"Cannot compute modular inverse of zero"`.
+ *
+ * @example
+ * ```typescript
+ * import { curve25519ModuloInv, curve25519ModuloMul } from "@umbra-privacy/sdk";
+ *
+ * const a = 7n;
+ * const invA = curve25519ModuloInv(a);
+ *
+ * // Verification: a × a^{-1} ≡ 1 (mod p)
+ * const product = curve25519ModuloMul(a, invA);
+ * console.log(product === 1n); // true
+ *
+ * // Throws for zero
+ * try {
+ *   curve25519ModuloInv(0n);
+ * } catch (e) {
+ *   console.log((e as Error).message); // "Cannot compute modular inverse of zero"
+ * }
+ * ```
+ *
+ * @see {@link curve25519ModuloPow} — the underlying exponentiation used internally
+ * @see {@link getCurve25519ModularInvFunction} — returns a cached reference to this function
+ *
+ * @public
+ */
+declare const curve25519ModuloInv: Curve25519ModuloInvFunction;
+/**
+ * Modular exponentiation for the Curve25519 base field.
+ *
+ * @remarks
+ * Computes the field power:
+ * ```
+ * result ≡ base^exp  (mod p),  p = 2^255 - 19
+ * ```
+ *
+ * Uses binary (square-and-multiply) exponentiation via {@link moduleExpLimbs}.
+ * The special case `exp === 0n` is handled explicitly: `base^0 = 1` for all
+ * `base`, including `base = 0`.
+ *
+ * This function satisfies {@link Curve25519ModuloPowFunction}.
+ *
+ * @param base - The base. Must be in canonical range [0, p-1].
+ * @param exp - A non-negative `bigint` exponent.
+ * @returns `base^exp mod p` in canonical range [0, p-1].
+ *
+ * @example
+ * ```typescript
+ * import { curve25519ModuloPow, CURVE25519_FIELD_PRIME } from "@umbra-privacy/sdk";
+ *
+ * // Small exponent
+ * const r1 = curve25519ModuloPow(2n, 10n);
+ * console.log(r1); // 1024n
+ *
+ * // Zero exponent: always 1
+ * const r2 = curve25519ModuloPow(12345n, 0n);
+ * console.log(r2); // 1n
+ *
+ * // Fermat's Little Theorem: a^(p-1) ≡ 1 for a ≠ 0
+ * const r3 = curve25519ModuloPow(42n, CURVE25519_FIELD_PRIME - 1n);
+ * console.log(r3); // 1n
+ * ```
+ *
+ * @see {@link curve25519ModuloInv} — uses this with exponent p-2
+ * @see {@link getCurve25519ModularPowFunction} — returns a cached reference to this function
+ *
+ * @public
+ */
+declare const curve25519ModuloPow: Curve25519ModuloPowFunction;
+/**
+ * Returns a lazily cached reference to the Curve25519 modular addition function.
+ *
+ * @remarks
+ * On the first call, stores `curve25519ModuloAdd` in the module-level cache
+ * variable and returns it. Subsequent calls return the cached reference
+ * without re-assignment. This pattern avoids redundant function object
+ * allocation when the getter is called in a hot path.
+ *
+ * The returned function is identical to calling {@link curve25519ModuloAdd}
+ * directly; the getter is provided for dependency-injection consumers that
+ * accept a `Curve25519ModuloAddFunction` from a provider rather than
+ * importing the concrete implementation.
+ *
+ * @returns The singleton `curve25519ModuloAdd` function.
+ *
+ * @example
+ * ```typescript
+ * import { getCurve25519ModularAddFunction } from "@umbra-privacy/sdk";
+ *
+ * const modAdd = getCurve25519ModularAddFunction();
+ * const sum = modAdd(10n, 20n); // 30n
+ * ```
+ *
+ * @see {@link curve25519ModuloAdd} — the underlying constant-time implementation
+ *
+ * @public
+ */
+declare function getCurve25519ModularAddFunction(): Curve25519ModuloAddFunction;
+/**
+ * Returns a lazily cached reference to the Curve25519 modular subtraction function.
+ *
+ * @remarks
+ * Follows the same lazy-caching pattern as {@link getCurve25519ModularAddFunction}.
+ * The returned function is identical to calling {@link curve25519ModuloSub} directly.
+ *
+ * @returns The singleton `curve25519ModuloSub` function.
+ *
+ * @example
+ * ```typescript
+ * import { getCurve25519ModularSubFunction } from "@umbra-privacy/sdk";
+ *
+ * const modSub = getCurve25519ModularSubFunction();
+ * const diff = modSub(30n, 10n); // 20n
+ * ```
+ *
+ * @see {@link curve25519ModuloSub} — the underlying constant-time implementation
+ *
+ * @public
+ */
+declare function getCurve25519ModularSubFunction(): Curve25519ModuloSubFunction;
+/**
+ * Returns a lazily cached reference to the Curve25519 modular multiplication function.
+ *
+ * @remarks
+ * Follows the same lazy-caching pattern as {@link getCurve25519ModularAddFunction}.
+ * The returned function is identical to calling {@link curve25519ModuloMul} directly.
+ *
+ * @returns The singleton `curve25519ModuloMul` function.
+ *
+ * @example
+ * ```typescript
+ * import { getCurve25519ModularMulFunction } from "@umbra-privacy/sdk";
+ *
+ * const modMul = getCurve25519ModularMulFunction();
+ * const product = modMul(7n, 8n); // 56n
+ * ```
+ *
+ * @see {@link curve25519ModuloMul} — the underlying implementation
+ *
+ * @public
+ */
+declare function getCurve25519ModularMulFunction(): Curve25519ModuloMulFunction;
+/**
+ * Returns a lazily cached reference to the Curve25519 modular inverse function.
+ *
+ * @remarks
+ * Follows the same lazy-caching pattern as {@link getCurve25519ModularAddFunction}.
+ * The returned function is identical to calling {@link curve25519ModuloInv} directly.
+ *
+ * @returns The singleton `curve25519ModuloInv` function.
+ *
+ * @example
+ * ```typescript
+ * import { getCurve25519ModularInvFunction } from "@umbra-privacy/sdk";
+ *
+ * const modInv = getCurve25519ModularInvFunction();
+ * const inverse = modInv(7n);
+ * // modInv(7n) * 7n ≡ 1 (mod p)
+ * ```
+ *
+ * @see {@link curve25519ModuloInv} — the underlying Fermat's theorem implementation
+ *
+ * @public
+ */
+declare function getCurve25519ModularInvFunction(): Curve25519ModuloInvFunction;
+/**
+ * Returns a lazily cached reference to the Curve25519 modular exponentiation function.
+ *
+ * @remarks
+ * Follows the same lazy-caching pattern as {@link getCurve25519ModularAddFunction}.
+ * The returned function is identical to calling {@link curve25519ModuloPow} directly.
+ *
+ * @returns The singleton `curve25519ModuloPow` function.
+ *
+ * @example
+ * ```typescript
+ * import { getCurve25519ModularPowFunction } from "@umbra-privacy/sdk";
+ *
+ * const modPow = getCurve25519ModularPowFunction();
+ * const result = modPow(2n, 10n); // 1024n
+ * ```
+ *
+ * @see {@link curve25519ModuloPow} — the underlying square-and-multiply implementation
+ *
+ * @public
+ */
+declare function getCurve25519ModularPowFunction(): Curve25519ModuloPowFunction;
+/**
+ * Factory that creates a sampler converting 512-bit big-endian byte arrays to
+ * uniformly distributed Curve25519 field elements.
+ *
+ * @remarks
+ * ## Purpose
+ *
+ * Hash-to-field algorithms produce 512-bit outputs to avoid statistical bias
+ * when mapping into the 255-bit field. This factory encapsulates the standard
+ * two-half combination technique (see below), returning a closure that can be
+ * used repeatedly.
+ *
+ * ## Algorithm
+ *
+ * Given a 64-byte big-endian input array:
+ *
+ * 1. **Split** into two 256-bit halves:
+ *    - `high = input[0..31]`  (most significant)
+ *    - `low  = input[32..63]` (least significant)
+ *
+ * 2. **Reduce** each half into [0, p) via constant-time trial subtraction
+ *    (`reduce256Curve25519`).
+ *
+ * 3. **Combine** using the precomputed constant R = 2^256 mod p = 38:
+ *    ```
+ *    result = (highReduced × R + lowReduced)  mod p
+ *    ```
+ *
+ * ## Customization via `deps`
+ *
+ * The `modAdd` and `modMul` slots in `deps` allow replacing the default
+ * constant-time implementations with alternatives. Common use cases:
+ * - Inject test stubs to exercise the combination logic in isolation.
+ * - Use a faster non-constant-time implementation for offline tooling.
+ *
+ * ## Uniformity
+ *
+ * The bias of the result is bounded by p / 2^512 < 2^-257, which is
+ * negligible for all practical cryptographic purposes.
+ *
+ * @param deps - Optional overrides for modular arithmetic. If omitted, uses
+ *   the default constant-time SDK implementations.
+ * @returns A closure `(input: U512BeBytes) => Curve25519FieldElement`.
+ *
+ * @example
+ * ```typescript
+ * import { getCurve25519FieldElementSampler } from "@umbra-privacy/sdk";
+ *
+ * // Default: uses SDK constant-time arithmetic
+ * const sampler = getCurve25519FieldElementSampler();
+ *
+ * const input = crypto.getRandomValues(new Uint8Array(64)) as U512BeBytes;
+ * const element = sampler(input);
+ * // element is a valid Curve25519FieldElement in [0, p-1]
+ *
+ * // With custom multiplication for testing
+ * const testSampler = getCurve25519FieldElementSampler({
+ *   modMul: (a, b) => (a * b) % ((1n << 255n) - 19n),
+ * });
+ * ```
+ *
+ * @see {@link curve25519FieldElementSampler} — pre-built default instance
+ * @see {@link U512BasedCurve25519FieldElementSamplerDeps} — the dependency injection bag
+ * @see {@link U512BasedCurve25519FieldElementSamplerFunction} — the returned function's type
+ *
+ * @public
+ */
+declare function getCurve25519FieldElementSampler(deps?: U512BasedCurve25519FieldElementSamplerDeps): U512BasedCurve25519FieldElementSamplerFunction;
+/**
+ * Pre-instantiated U512-to-field-element sampler using the default
+ * constant-time Curve25519 field arithmetic.
+ *
+ * @remarks
+ * This is a convenience export for callers that do not need to inject custom
+ * arithmetic. It is equivalent to calling:
+ * ```typescript
+ * getCurve25519FieldElementSampler()
+ * ```
+ * but avoids the factory call overhead for the common case.
+ *
+ * ## Typical Usage Pattern
+ *
+ * Hash-to-field: pass the 512-bit output of a wide hash (SHA-512, BLAKE2b-512,
+ * HKDF output, etc.) directly to this sampler to obtain a uniformly distributed
+ * field element:
+ * ```
+ * fieldElement = sampler(sha512(domainSeparator || message))
+ * ```
+ *
+ * This pattern is used internally in the Umbra SDK wherever a scalar must be
+ * derived deterministically from a secret without bias.
+ *
+ * @param input - A 64-byte big-endian byte array (`U512BeBytes`).
+ * @returns A `Curve25519FieldElement` in the canonical range [0, p-1].
+ *
+ * @example
+ * ```typescript
+ * import { curve25519FieldElementSampler } from "@umbra-privacy/sdk";
+ *
+ * // All-zero input → deterministic result (== 0n)
+ * const zeroInput = new Uint8Array(64) as U512BeBytes;
+ * const element = curve25519FieldElementSampler(zeroInput);
+ * console.log(element); // 0n
+ *
+ * // Random 64-byte input from a CSPRNG
+ * const randomInput = crypto.getRandomValues(new Uint8Array(64)) as U512BeBytes;
+ * const randomElement = curve25519FieldElementSampler(randomInput);
+ * // randomElement is uniformly distributed in [0, p-1]
+ * ```
+ *
+ * @see {@link getCurve25519FieldElementSampler} — factory for custom arithmetic
+ * @see {@link U512BasedCurve25519FieldElementSamplerFunction} — the function type
+ *
+ * @public
+ */
+declare const curve25519FieldElementSampler: U512BasedCurve25519FieldElementSamplerFunction;
+
+export { bn254Add, bn254FieldElementSampler, bn254ModuloPow, bn254Mul, bn254Sub, computeBn254LimbwiseSumInverse, computeBn254ModularInverse, curve25519FieldElementSampler, curve25519ModuloAdd, curve25519ModuloInv, curve25519ModuloMul, curve25519ModuloPow, curve25519ModuloSub, getBn254FieldElementSampler, getBn254ModularAdder, getBn254ModularInverter, getBn254ModularMultiplier, getBn254ModularNegator, getBn254ModularSubtractor, getCurve25519FieldElementSampler, getCurve25519ModularAddFunction, getCurve25519ModularInvFunction, getCurve25519ModularMulFunction, getCurve25519ModularPowFunction, getCurve25519ModularSubFunction };