@noble/curves 2.0.1 → 2.2.0

package/ed448.d.ts

@@ -1,12 +1,16 @@
 import type { AffinePoint } from './abstract/curve.ts';
 import { PrimeEdwardsPoint, type EdDSA, type EdwardsPoint, type EdwardsPointCons } from './abstract/edwards.ts';
+import { type FROST } from './abstract/frost.ts';
 import { type H2CHasher, type H2CHasherBase } from './abstract/hash-to-curve.ts';
 import { type IField } from './abstract/modular.ts';
 import { type MontgomeryECDH } from './abstract/montgomery.ts';
 import { type OPRF } from './abstract/oprf.ts';
+import { type TArg, type TRet } from './utils.ts';
 /**
  * ed448 EdDSA curve and methods.
  * @example
+ * Generate one Ed448 keypair, sign a message, and verify it.
+ *
  * ```js
  * import { ed448 } from '@noble/curves/ed448.js';
  * const { secretKey, publicKey } = ed448.keygen();
@@ -17,17 +21,46 @@ import { type OPRF } from './abstract/oprf.ts';
  * ```
  */
 export declare const ed448: EdDSA;
-/** Prehashed version of ed448. See {@link ed448} */
+/**
+ * Prehashed version of ed448. See {@link ed448}
+ * @example
+ * Use the prehashed Ed448 variant for one message.
+ *
+ * ```ts
+ * const { secretKey, publicKey } = ed448ph.keygen();
+ * const msg = new TextEncoder().encode('hello noble');
+ * const sig = ed448ph.sign(msg, secretKey);
+ * const isValid = ed448ph.verify(sig, msg, publicKey);
+ * ```
+ */
 export declare const ed448ph: EdDSA;
 /**
- * E448 (NIST) != edwards448 used in ed448.
- * E448 is birationally equivalent to edwards448.
+ * E448 here is NIST SP 800-186 §3.2.3.3 E448, the Edwards representation of
+ * Curve448, not RFC 8032 edwards448 / Goldilocks.
+ * Goldilocks is the separate 4-isogenous curve exposed as `ed448`.
+ * We keep the corrected prime-order base here; RFC 7748's literal Edwards
+ * point / map are wrong for this curve model, and the literal point is the
+ * wrong-sign order-2*n variant.
+ * @param X - Projective X coordinate.
+ * @param Y - Projective Y coordinate.
+ * @param Z - Projective Z coordinate.
+ * @param T - Projective T coordinate.
+ * @example
+ * Multiply the E448 base point.
+ *
+ * ```ts
+ * const point = E448.BASE.multiply(2n);
+ * ```
  */
 export declare const E448: EdwardsPointCons;
 /**
  * ECDH using curve448 aka x448.
+ * The wrapper aborts on all-zero shared secrets by default, and seeded
+ * `keygen(seed)` reuses the provided 56-byte seed buffer instead of copying it.
  *
  * @example
+ * Derive one shared secret between two X448 peers.
+ *
  * ```js
  * import { x448 } from '@noble/curves/ed448.js';
  * const alice = x448.keygen();
@@ -35,9 +68,33 @@ export declare const E448: EdwardsPointCons;
  * const shared = x448.getSharedSecret(alice.secretKey, bob.publicKey);
  * ```
  */
-export declare const x448: MontgomeryECDH;
-/** Hashing / encoding to ed448 points / field. RFC 9380 methods. */
+export declare const x448: TRet<MontgomeryECDH>;
+/**
+ * Hashing / encoding to ed448 points / field. RFC 9380 methods.
+ * Public `mapToCurve()` consumes one field element bigint for `m = 1`, and RFC
+ * Appendix J vectors use the special `QUUX-V01-*` test DST overrides rather
+ * than the default suite IDs below.
+ * @example
+ * Hash one message onto the ed448 curve.
+ *
+ * ```ts
+ * const point = ed448_hasher.hashToCurve(new TextEncoder().encode('hello noble'));
+ * ```
+ */
 export declare const ed448_hasher: H2CHasher<EdwardsPointCons>;
+/**
+ * FROST threshold signatures over ed448. RFC 9591.
+ * @example
+ * Create one trusted-dealer package for 2-of-3 ed448 signing.
+ *
+ * ```ts
+ * const alice = ed448_FROST.Identifier.derive('alice@example.com');
+ * const bob = ed448_FROST.Identifier.derive('bob@example.com');
+ * const carol = ed448_FROST.Identifier.derive('carol@example.com');
+ * const deal = ed448_FROST.trustedDealer({ min: 2, max: 3 }, [alice, bob, carol]);
+ * ```
+ */
+export declare const ed448_FROST: TRet<FROST>;
 /**
  * Each ed448/EdwardsPoint has 4 different equivalent points. This can be
  * a source of bugs for protocols like ring signatures. Decaf was created to solve this.
@@ -51,21 +108,27 @@ declare class _DecafPoint extends PrimeEdwardsPoint<_DecafPoint> {
     static Fp: IField<bigint>;
     static Fn: IField<bigint>;
     constructor(ep: EdwardsPoint);
+    /**
+     * Create one Decaf448 point from affine Edwards coordinates.
+     * This wraps the internal Edwards representative directly and is not a
+     * canonical decaf448 decoding path.
+     * Use `toBytes()` / `fromBytes()` if canonical decaf448 bytes matter.
+     */
     static fromAffine(ap: AffinePoint<bigint>): _DecafPoint;
     protected assertSame(other: _DecafPoint): void;
     protected init(ep: EdwardsPoint): _DecafPoint;
-    static fromBytes(bytes: Uint8Array): _DecafPoint;
+    static fromBytes(bytes: TArg<Uint8Array>): _DecafPoint;
     /**
      * Converts decaf-encoded string to decaf point.
      * Described in [RFC9496](https://www.rfc-editor.org/rfc/rfc9496#name-decode-2).
-     * @param hex Decaf-encoded 56 bytes. Not every 56-byte string is valid decaf encoding
+     * @param hex - Decaf-encoded 56 bytes. Not every 56-byte string is valid decaf encoding
      */
     static fromHex(hex: string): _DecafPoint;
     /**
      * Encodes decaf point to Uint8Array.
      * Described in [RFC9496](https://www.rfc-editor.org/rfc/rfc9496#name-encode-2).
      */
-    toBytes(): Uint8Array;
+    toBytes(): TRet<Uint8Array>;
     /**
      * Compare one point to another.
      * Described in [RFC9496](https://www.rfc-editor.org/rfc/rfc9496#name-equals-2).
@@ -73,19 +136,50 @@ declare class _DecafPoint extends PrimeEdwardsPoint<_DecafPoint> {
     equals(other: _DecafPoint): boolean;
     is0(): boolean;
 }
+/** Prime-order Decaf448 group bundle. */
 export declare const decaf448: {
     Point: typeof _DecafPoint;
 };
-/** Hashing to decaf448 points / field. RFC 9380 methods. */
+/**
+ * Hashing to decaf448 points / field. RFC 9380 methods.
+ * `hashToCurve()` is RFC 9380 `hash_to_decaf448`, `deriveToCurve()` is RFC
+ * 9496 element derivation, and `hashToScalar()` is a library helper layered on
+ * top of RFC 9496 scalar reduction.
+ * @example
+ * Hash one message onto decaf448.
+ *
+ * ```ts
+ * const point = decaf448_hasher.hashToCurve(new TextEncoder().encode('hello noble'));
+ * ```
+ */
 export declare const decaf448_hasher: H2CHasherBase<typeof _DecafPoint>;
-/** decaf448 OPRF, defined in RFC 9497. */
-export declare const decaf448_oprf: OPRF;
+/**
+ * decaf448 OPRF, defined in RFC 9497.
+ * @example
+ * Run one blind/evaluate/finalize OPRF round over decaf448.
+ *
+ * ```ts
+ * const input = new TextEncoder().encode('hello noble');
+ * const keys = decaf448_oprf.oprf.generateKeyPair();
+ * const blind = decaf448_oprf.oprf.blind(input);
+ * const evaluated = decaf448_oprf.oprf.blindEvaluate(keys.secretKey, blind.blinded);
+ * const output = decaf448_oprf.oprf.finalize(input, blind.blind, evaluated);
+ * ```
+ */
+export declare const decaf448_oprf: TRet<OPRF>;
 /**
  * Weird / bogus points, useful for debugging.
  * Unlike ed25519, there is no ed448 generator point which can produce full T subgroup.
- * Instead, there is a Klein four-group, which spans over 2 independent 2-torsion points:
- * (0, 1), (0, -1), (-1, 0), (1, 0).
+ * Instead, the torsion subgroup here is cyclic of order 4, generated by
+ * `(1, 0)`, and the array below lists that subgroup set (Klein four-group).
+ * @example
+ * Decode one known torsion point for debugging.
+ *
+ * ```ts
+ * import { ED448_TORSION_SUBGROUP, ed448 } from '@noble/curves/ed448.js';
+ * const point = ed448.Point.fromHex(ED448_TORSION_SUBGROUP[1]);
+ * ```
  */
-export declare const ED448_TORSION_SUBGROUP: string[];
+export declare const ED448_TORSION_SUBGROUP: readonly string[];
 export {};
 //# sourceMappingURL=ed448.d.ts.map

package/ed448.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ed448.d.ts","sourceRoot":"","sources":["src/ed448.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAGL,iBAAiB,EACjB,KAAK,KAAK,EAGV,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAKL,KAAK,SAAS,EACd,KAAK,aAAa,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAiD,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACnG,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAc,KAAK,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAoI3D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,KAAK,EAAE,KAA+B,CAAC;AAGpD,oDAAoD;AACpD,eAAO,MAAM,OAAO,EAAE,KAAqD,CAAC;AAC5E;;;GAGG;AACH,eAAO,MAAM,IAAI,EAAE,gBAAsD,CAAC;AAE1E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,IAAI,EAAE,cAYf,CAAC;AA+EL,oEAAoE;AACpE,eAAO,MAAM,YAAY,EAAE,SAAS,CAAC,gBAAgB,CAS9C,CAAC;AAkDR;;;;;;GAMG;AACH,cAAM,WAAY,SAAQ,iBAAiB,CAAC,WAAW,CAAC;IAGtD,MAAM,CAAC,IAAI,EAAE,WAAW,CAC0D;IAElF,MAAM,CAAC,IAAI,EAAE,WAAW,CACsC;IAE9D,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,CACS;IAElC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,CACS;gBAEtB,EAAE,EAAE,YAAY;IAI5B,MAAM,CAAC,UAAU,CAAC,EAAE,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,WAAW;IAIvD,SAAS,CAAC,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAI9C,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,YAAY,GAAG,WAAW;IAI7C,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW;IA6BhD;;;;OAIG;IACH,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW;IAIxC;;;OAGG;IACH,OAAO,IAAI,UAAU;IAerB;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;IAQnC,GAAG,IAAI,OAAO;CAGf;AAED,eAAO,MAAM,QAAQ,EAAE;IACrB,KAAK,EAAE,OAAO,WAAW,CAAC;CACF,CAAC;AAE3B,4DAA4D;AAC5D,eAAO,MAAM,eAAe,EAAE,aAAa,CAAC,OAAO,WAAW,CAmC7D,CAAC;AAEF,0CAA0C;AAC1C,eAAO,MAAM,aAAa,EAAE,IAOrB,CAAC;AAER;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,EAK1C,CAAC"}
+{"version":3,"file":"ed448.d.ts","sourceRoot":"","sources":["src/ed448.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAGL,iBAAiB,EACjB,KAAK,KAAK,EAGV,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAKL,KAAK,SAAS,EACd,KAAK,aAAa,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAiD,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACnG,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAc,KAAK,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAKL,KAAK,IAAI,EACT,KAAK,IAAI,EACV,MAAM,YAAY,CAAC;AAyJpB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,KAAK,EAAE,KAA+B,CAAC;AAGpD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,EAAE,KAAqD,CAAC;AAC5E;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,IAAI,EAAE,gBAAsD,CAAC;AAE1E;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,IAAI,EAAE,IAAI,CAAC,cAAc,CAYlC,CAAC;AAqFL;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,CAAC,gBAAgB,CAS9C,CAAC;AACR;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,IAAI,CAAC,KAAK,CAa7B,CAAC;AAwER;;;;;;GAMG;AACH,cAAM,WAAY,SAAQ,iBAAiB,CAAC,WAAW,CAAC;IAGtD,MAAM,CAAC,IAAI,EAAE,WAAW,CACoF;IAE5G,MAAM,CAAC,IAAI,EAAE,WAAW,CACsC;IAE9D,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,CACS;IAElC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,CACS;gBAEtB,EAAE,EAAE,YAAY;IAI5B;;;;;OAKG;IACH,MAAM,CAAC,UAAU,CAAC,EAAE,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,WAAW;IAIvD,SAAS,CAAC,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAI9C,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,YAAY,GAAG,WAAW;IAI7C,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,GAAG,WAAW;IA6BtD;;;;OAIG;IACH,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW;IAIxC;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAC,UAAU,CAAC;IAe3B;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;IAQnC,GAAG,IAAI,OAAO;CAGf;AAMD,yCAAyC;AACzC,eAAO,MAAM,QAAQ,EAAE;IACrB,KAAK,EAAE,OAAO,WAAW,CAAC;CAC6B,CAAC;AAE1D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,EAAE,aAAa,CAAC,OAAO,WAAW,CAsC5D,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,EAAE,IAAI,CAAC,IAAI,CAO9B,CAAC;AAER;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAKlD,CAAC"}

package/ed448.js

@@ -1,5 +1,5 @@
 /**
- * Edwards448 (not Ed448-Goldilocks) curve with following addons:
+ * Edwards448 (also called Goldilocks) curve with following addons:
  * - X448 ECDH
  * - Decaf cofactor elimination
  * - Elligator hash-to-group / point indistinguishability
@@ -10,18 +10,19 @@
 import { shake256 } from '@noble/hashes/sha3.js';
 import { concatBytes, hexToBytes, createHasher as wrapConstructor } from '@noble/hashes/utils.js';
 import { eddsa, edwards, PrimeEdwardsPoint, } from "./abstract/edwards.js";
+import { createFROST } from "./abstract/frost.js";
 import { _DST_scalar, createHasher, expand_message_xof, } from "./abstract/hash-to-curve.js";
 import { Field, FpInvertBatch, isNegativeLE, mod, pow2 } from "./abstract/modular.js";
 import { montgomery } from "./abstract/montgomery.js";
-import { createORPF } from "./abstract/oprf.js";
-import { abytes, asciiToBytes, bytesToNumberLE, equalBytes } from "./utils.js";
+import { createOPRF } from "./abstract/oprf.js";
+import { abytes, asciiToBytes, bytesToNumberLE, equalBytes, } from "./utils.js";
 // edwards448 curve
 // a = 1n
 // d = Fp.neg(39081n)
 // Finite field 2n**448n - 2n**224n - 1n
 // Subgroup order
 // 2n**446n - 13818066809895115352007386748515426880336692474882178609894547503885n
-const ed448_CURVE_p = BigInt('0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffeffffffffffffffffffffffffffffffffffffffffffffffffffffffff');
+const ed448_CURVE_p = /* @__PURE__ */ BigInt('0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffeffffffffffffffffffffffffffffffffffffffffffffffffffffffff');
 const ed448_CURVE = /* @__PURE__ */ (() => ({
     p: ed448_CURVE_p,
     n: BigInt('0x3fffffffffffffffffffffffffffffffffffffffffffffffffffffff7cca23e9c44edb49aed63690216cc2728dc58f552378c292ab5844f3'),
@@ -31,9 +32,14 @@ const ed448_CURVE = /* @__PURE__ */ (() => ({
     Gx: BigInt('0x4f1970c66bed0ded221d15a622bf36da9e146570470f1767ea6de324a3d3a46412ae1af72ab66511433b80e18b00938e2626a82bc70cc05e'),
     Gy: BigInt('0x693f46716eb6bc248876203756c9c7624bea73736ca3984087789c1e05a0c2d73ad3ff1ce67c39c4fdbd132c4ed7c8ad9808795bf230fa14'),
 }))();
-// E448 NIST curve is identical to edwards448, except for:
-// d = 39082/39081
-// Gx = 3/2
+// This is not RFC 8032 edwards448 / Goldilocks (`ed448` below, d = -39081).
+// It is NIST SP 800-186 §3.2.3.3 E448, the Curve448-isomorphic Edwards model
+// also described in draft-ietf-lwig-curve-representations-23 Appendix M, with
+// d = 39082/39081 and Gy = 3/2.
+// RFC 7748's literal Edwards point / birational map are wrong here: the literal
+// point is the wrong-sign (Gx, -Gy) order-2*n variant. Keep the corrected
+// prime-order (Gx, Gy) base so Point.BASE stays a subgroup generator, which is
+// what noble's generic Edwards API expects.
 const E448_CURVE = /* @__PURE__ */ (() => Object.assign({}, ed448_CURVE, {
     d: BigInt('0xd78b4bdc7f0daf19f24f38c29373a2ccad46157242a50f37809b1da3412a12e79ccc9c81264cfe9ad080997058fb61c4243cc32dbaa156b9'),
     Gx: BigInt('0x79a70b2b70400553ae7c9df416c792c61128751ac92969240c25a07d728bdc93e21f7787ed6972249de732f38496cd11698713093e9c04fc'),
@@ -42,9 +48,9 @@ const E448_CURVE = /* @__PURE__ */ (() => Object.assign({}, ed448_CURVE, {
 const shake256_114 = /* @__PURE__ */ wrapConstructor(() => shake256.create({ dkLen: 114 }));
 const shake256_64 = /* @__PURE__ */ wrapConstructor(() => shake256.create({ dkLen: 64 }));
 // prettier-ignore
-const _1n = BigInt(1), _2n = BigInt(2), _3n = BigInt(3), _4n = /* @__PURE__ */ BigInt(4), _11n = BigInt(11);
+const _1n = /* @__PURE__ */ BigInt(1), _2n = /* @__PURE__ */ BigInt(2), _3n = /* @__PURE__ */ BigInt(3), _4n = /* @__PURE__ */ BigInt(4), _11n = /* @__PURE__ */ BigInt(11);
 // prettier-ignore
-const _22n = BigInt(22), _44n = BigInt(44), _88n = BigInt(88), _223n = BigInt(223);
+const _22n = /* @__PURE__ */ BigInt(22), _44n = /* @__PURE__ */ BigInt(44), _88n = /* @__PURE__ */ BigInt(88), _223n = /* @__PURE__ */ BigInt(223);
 // powPminus3div4 calculates z = x^k mod p, where k = (p-3)/4.
 // Used for efficient square root calculation.
 // ((P-3)/4).toString(2) would produce bits [223x 1, 0, 222x 1]
@@ -64,6 +70,8 @@ function ed448_pow_Pminus3div4(x) {
     const b223 = (pow2(b222, _1n, P) * x) % P;
     return (pow2(b223, _223n, P) * b222) % P;
 }
+// Mutates and returns the provided buffer in place. The final `bytes[56] = 0`
+// write is the Ed448 path; for 56-byte X448 inputs it is an out-of-bounds no-op.
 function adjustScalarBytes(bytes) {
     // Section 5: Likewise, for X448, set the two least significant bits of the first byte to 0,
     bytes[0] &= 252; // 0b11111100
@@ -73,8 +81,9 @@ function adjustScalarBytes(bytes) {
     bytes[56] = 0; // Byte outside of group (456 buts vs 448 bits)
     return bytes;
 }
-// Constant-time ratio of u to v. Allows to combine inversion and square root u/√v.
-// Uses algo from RFC8032 5.1.3.
+// Constant-time Ed448 decode helper for RFC 8032 §5.2.3 steps 2-3. Unlike
+// `SQRT_RATIO_M1`, the returned `value` only has the documented meaning when
+// `isValid` is true.
 function uvRatio(u, v) {
     const P = ed448_CURVE_p;
     // https://www.rfc-editor.org/rfc/rfc8032#section-5.2.3
@@ -95,27 +104,39 @@ function uvRatio(u, v) {
     return { isValid: mod(x2 * v, P) === u, value: x };
 }
 // Finite field 2n**448n - 2n**224n - 1n
-// The value fits in 448 bits, but we use 456-bit (57-byte) elements because of bitflags.
-// - ed25519 fits in 255 bits, allowing using last 1 byte for specifying bit flag of point negation.
-// - ed448 fits in 448 bits. We can't use last 1 byte: we can only use a bit 224 in the middle.
+// RFC 8032 encodes Ed448 field/scalar elements in 57 bytes even though field
+// values fit in 448 bits and scalars in 446 bits. Noble models that with a
+// 456-bit storage width so the final-octet x-sign bit (bit 455) still fits in
+// the shared little-endian container.
 const Fp = /* @__PURE__ */ (() => Field(ed448_CURVE_p, { BITS: 456, isLE: true }))();
+// Same 57-byte container shape as `Fp`; canonical scalar encodings still have
+// the top ten bits clear per RFC 8032.
 const Fn = /* @__PURE__ */ (() => Field(ed448_CURVE.n, { BITS: 456, isLE: true }))();
-// decaf448 uses 448-bit (56-byte) keys
+// Generic 56-byte field shape used by decaf448 and raw X448 u-coordinates.
+// Plain `Field` decoding stays canonical here, so callers that want RFC 7748's
+// modulo-p acceptance must reduce externally.
 const Fp448 = /* @__PURE__ */ (() => Field(ed448_CURVE_p, { BITS: 448, isLE: true }))();
+// Strict 56-byte scalar parser matching RFC 9496's recommended canonical form.
 const Fn448 = /* @__PURE__ */ (() => Field(ed448_CURVE.n, { BITS: 448, isLE: true }))();
 // SHAKE256(dom4(phflag,context)||x, 114)
+// RFC 8032 `dom4` prefix. Empty contexts are valid; the accepted length range
+// is 0..255 octets inclusive.
 function dom4(data, ctx, phflag) {
     if (ctx.length > 255)
         throw new Error('context must be smaller than 255, got: ' + ctx.length);
     return concatBytes(asciiToBytes('SigEd448'), new Uint8Array([phflag ? 1 : 0, ctx.length]), ctx, data);
 }
 const ed448_Point = /* @__PURE__ */ edwards(ed448_CURVE, { Fp, Fn, uvRatio });
+// Shared internal factory for both `ed448` and `ed448ph`; callers are only
+// expected to override narrow family options such as prehashing.
 function ed4(opts) {
     return eddsa(ed448_Point, shake256_114, Object.assign({ adjustScalarBytes, domain: dom4 }, opts));
 }
 /**
  * ed448 EdDSA curve and methods.
  * @example
+ * Generate one Ed448 keypair, sign a message, and verify it.
+ *
  * ```js
  * import { ed448 } from '@noble/curves/ed448.js';
  * const { secretKey, publicKey } = ed448.keygen();
@@ -127,17 +148,46 @@ function ed4(opts) {
  */
 export const ed448 = /* @__PURE__ */ ed4({});
 // There is no ed448ctx, since ed448 supports ctx by default
-/** Prehashed version of ed448. See {@link ed448} */
+/**
+ * Prehashed version of ed448. See {@link ed448}
+ * @example
+ * Use the prehashed Ed448 variant for one message.
+ *
+ * ```ts
+ * const { secretKey, publicKey } = ed448ph.keygen();
+ * const msg = new TextEncoder().encode('hello noble');
+ * const sig = ed448ph.sign(msg, secretKey);
+ * const isValid = ed448ph.verify(sig, msg, publicKey);
+ * ```
+ */
 export const ed448ph = /* @__PURE__ */ ed4({ prehash: shake256_64 });
 /**
- * E448 (NIST) != edwards448 used in ed448.
- * E448 is birationally equivalent to edwards448.
+ * E448 here is NIST SP 800-186 §3.2.3.3 E448, the Edwards representation of
+ * Curve448, not RFC 8032 edwards448 / Goldilocks.
+ * Goldilocks is the separate 4-isogenous curve exposed as `ed448`.
+ * We keep the corrected prime-order base here; RFC 7748's literal Edwards
+ * point / map are wrong for this curve model, and the literal point is the
+ * wrong-sign order-2*n variant.
+ * @param X - Projective X coordinate.
+ * @param Y - Projective Y coordinate.
+ * @param Z - Projective Z coordinate.
+ * @param T - Projective T coordinate.
+ * @example
+ * Multiply the E448 base point.
+ *
+ * ```ts
+ * const point = E448.BASE.multiply(2n);
+ * ```
  */
 export const E448 = /* @__PURE__ */ edwards(E448_CURVE);
 /**
  * ECDH using curve448 aka x448.
+ * The wrapper aborts on all-zero shared secrets by default, and seeded
+ * `keygen(seed)` reuses the provided 56-byte seed buffer instead of copying it.
  *
  * @example
+ * Derive one shared secret between two X448 peers.
+ *
  * ```js
  * import { x448 } from '@noble/curves/ed448.js';
  * const alice = x448.keygen();
@@ -159,8 +209,11 @@ export const x448 = /* @__PURE__ */ (() => {
     });
 })();
 // Hash To Curve Elligator2 Map
-const ELL2_C1 = /* @__PURE__ */ (() => (ed448_CURVE_p - BigInt(3)) / BigInt(4))(); // 1. c1 = (q - 3) / 4         # Integer arithmetic
+// 1. c1 = (q - 3) / 4 # Integer arithmetic
+const ELL2_C1 = /* @__PURE__ */ (() => (ed448_CURVE_p - BigInt(3)) / BigInt(4))();
 const ELL2_J = /* @__PURE__ */ BigInt(156326);
+// Returns RFC 9380 Appendix G.2.3 rational Montgomery numerators/denominators
+// `{ xn, xd, yn, yd }`, not an affine point.
 function map_to_curve_elligator2_curve448(u) {
     let tv1 = Fp.sqr(u); // 1.  tv1 = u^2
     let e1 = Fp.eql(tv1, Fp.ONE); // 2.   e1 = tv1 == 1
@@ -178,7 +231,8 @@ function map_to_curve_elligator2_curve448(u) {
     tv3 = Fp.mul(tv3, tv2); // 14. tv3 = tv3 * tv2         # gx1 * gxd^3
     let y1 = Fp.pow(tv3, ELL2_C1); // 15.  y1 = tv3^c1            # (gx1 * gxd^3)^((p - 3) / 4)
     y1 = Fp.mul(y1, tv2); // 16.  y1 = y1 * tv2          # gx1 * gxd * (gx1 * gxd^3)^((p - 3) / 4)
-    let x2n = Fp.mul(x1n, Fp.neg(tv1)); // 17. x2n = -tv1 * x1n        # x2 = x2n / xd = -1 * u^2 * x1n / xd
+    // 17. x2n = -tv1 * x1n # x2 = x2n / xd = -1 * u^2 * x1n / xd
+    let x2n = Fp.mul(x1n, Fp.neg(tv1));
     let y2 = Fp.mul(y1, u); // 18.  y2 = y1 * u
     y2 = Fp.cmov(y2, Fp.ZERO, e1); // 19.  y2 = CMOV(y2, 0, e1)
     tv2 = Fp.sqr(y1); // 20. tv2 = y1^2
@@ -190,8 +244,10 @@ function map_to_curve_elligator2_curve448(u) {
     y = Fp.cmov(y, Fp.neg(y), e2 !== e3); // 26.   y = CMOV(y, -y, e2 XOR e3)
     return { xn, xd, yn: y, yd: Fp.ONE }; // 27. return (xn, xd, y, 1)
 }
+// Returns affine `{ x, y }` after inverting the Appendix G.2.4 denominators.
 function map_to_curve_elligator2_edwards448(u) {
-    let { xn, xd, yn, yd } = map_to_curve_elligator2_curve448(u); // 1. (xn, xd, yn, yd) = map_to_curve_elligator2_curve448(u)
+    // 1. (xn, xd, yn, yd) = map_to_curve_elligator2_curve448(u)
+    let { xn, xd, yn, yd } = map_to_curve_elligator2_curve448(u);
     let xn2 = Fp.sqr(xn); // 2.  xn2 = xn^2
     let xd2 = Fp.sqr(xd); // 3.  xd2 = xd^2
     let xd4 = Fp.sqr(xd2); // 4.  xd4 = xd2^2
@@ -231,7 +287,18 @@ function map_to_curve_elligator2_edwards448(u) {
     const inv = FpInvertBatch(Fp, [xEd, yEd], true); // batch division
     return { x: Fp.mul(xEn, inv[0]), y: Fp.mul(yEn, inv[1]) }; // 38. return (xEn, xEd, yEn, yEd)
 }
-/** Hashing / encoding to ed448 points / field. RFC 9380 methods. */
+/**
+ * Hashing / encoding to ed448 points / field. RFC 9380 methods.
+ * Public `mapToCurve()` consumes one field element bigint for `m = 1`, and RFC
+ * Appendix J vectors use the special `QUUX-V01-*` test DST overrides rather
+ * than the default suite IDs below.
+ * @example
+ * Hash one message onto the ed448 curve.
+ *
+ * ```ts
+ * const point = ed448_hasher.hashToCurve(new TextEncoder().encode('hello noble'));
+ * ```
+ */
 export const ed448_hasher = /* @__PURE__ */ (() => createHasher(ed448_Point, (scalars) => map_to_curve_elligator2_edwards448(scalars[0]), {
     DST: 'edwards448_XOF:SHAKE256_ELL2_RO_',
     encodeDST: 'edwards448_XOF:SHAKE256_ELL2_NU_',
@@ -241,6 +308,32 @@ export const ed448_hasher = /* @__PURE__ */ (() => createHasher(ed448_Point, (sc
     expand: 'xof',
     hash: shake256,
 }))();
+/**
+ * FROST threshold signatures over ed448. RFC 9591.
+ * @example
+ * Create one trusted-dealer package for 2-of-3 ed448 signing.
+ *
+ * ```ts
+ * const alice = ed448_FROST.Identifier.derive('alice@example.com');
+ * const bob = ed448_FROST.Identifier.derive('bob@example.com');
+ * const carol = ed448_FROST.Identifier.derive('carol@example.com');
+ * const deal = ed448_FROST.trustedDealer({ min: 2, max: 3 }, [alice, bob, carol]);
+ * ```
+ */
+export const ed448_FROST = /* @__PURE__ */ (() => createFROST({
+    name: 'FROST-ED448-SHAKE256-v1',
+    Point: ed448_Point,
+    validatePoint: (p) => {
+        p.assertValidity();
+        if (!p.isTorsionFree())
+            throw new Error('bad point: not torsion-free');
+    },
+    // Group:  edwards448 [RFC8032], where Ne = 57 and Ns = 57.
+    // Fn is 57 bytes, Fp is 57 bytes too
+    Fn,
+    hash: shake256_114,
+    H2: 'SigEd448\0\0',
+}))();
 // 1-d
 const ONE_MINUS_D = /* @__PURE__ */ BigInt('39082');
 // 1-2d
@@ -249,12 +342,21 @@ const ONE_MINUS_TWO_D = /* @__PURE__ */ BigInt('78163');
 const SQRT_MINUS_D = /* @__PURE__ */ BigInt('98944233647732219769177004876929019128417576295529901074099889598043702116001257856802131563896515373927712232092845883226922417596214');
 // 1 / √(-d)
 const INVSQRT_MINUS_D = /* @__PURE__ */ BigInt('315019913931389607337177038330951043522456072897266928557328499619017160722351061360252776265186336876723201881398623946864393857820716');
-// Calculates 1/√(number)
-const invertSqrt = (number) => uvRatio(_1n, number);
+// RFC 9496 `SQRT_RATIO_M1` must return `CT_ABS(s)`, i.e. the nonnegative root.
+// Keep this Decaf-local: RFC 9496 decode/encode/map formulas depend on that
+// canonical representative, while ordinary Ed448 decoding still uses `uvRatio()`
+// plus the public sign bit from RFC 8032.
+const sqrtRatioM1 = (u, v) => {
+    const P = ed448_CURVE_p;
+    const { isValid, value } = uvRatio(u, v);
+    return { isValid, value: isNegativeLE(value, P) ? Fp448.create(-value) : value };
+};
+const invertSqrt = (number) => sqrtRatioM1(_1n, number);
 /**
  * Elligator map for hash-to-curve of decaf448.
- * Described in [RFC9380](https://www.rfc-editor.org/rfc/rfc9380#appendix-C)
- * and [RFC9496](https://www.rfc-editor.org/rfc/rfc9496#name-element-derivation-2).
+ * Primary formula source is RFC 9496 §5.3.4. Step 1 intentionally reduces the
+ * input modulo `p`, and the return value is the internal Edwards
+ * representation, not a public decaf encoding.
  */
 function calcElligatorDecafMap(r0) {
     const { d, p: P } = ed448_CURVE;
@@ -262,7 +364,7 @@ function calcElligatorDecafMap(r0) {
     const r = mod(-(r0 * r0)); // 1
     const u0 = mod(d * (r - _1n)); // 2
     const u1 = mod((u0 + _1n) * (u0 - r)); // 3
-    const { isValid: was_square, value: v } = uvRatio(ONE_MINUS_TWO_D, mod((r + _1n) * u1)); // 4
+    const { isValid: was_square, value: v } = sqrtRatioM1(ONE_MINUS_TWO_D, mod((r + _1n) * u1)); // 4
     let v_prime = v; // 5
     if (!was_square)
         v_prime = mod(r0 * v);
@@ -280,6 +382,12 @@ function calcElligatorDecafMap(r0) {
     const W3 = mod(v_prime * s * (r - _1n) * ONE_MINUS_TWO_D + sgn); // 11
     return new ed448_Point(mod(W0 * W3), mod(W2 * W1), mod(W1 * W3), mod(W0 * W2));
 }
+// Keep the Decaf448 base representative literal here: deriving it with
+// `new _DecafPoint(ed448_Point.BASE).multiplyUnsafe(2)` forces eager WNAF precomputes and
+// adds about 100ms to `ed448.js` import time.
+const DECAF_BASE_X = /* @__PURE__ */ BigInt('0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa955555555555555555555555555555555555555555555555555555555');
+const DECAF_BASE_Y = /* @__PURE__ */ BigInt('0xae05e9634ad7048db359d6205086c2b0036ed7a035884dd7b7e36d728ad8c4b80d6565833a2a3098bbbcb2bed1cda06bdaeafbcdea9386ed');
+const DECAF_BASE_T = /* @__PURE__ */ BigInt('0x696d84643374bace9d70983a12aa9d461da74d2d5c35e8d97ba72c3aba4450a5d29274229bd22c1d5e3a6474ee4ffb0e7a9e200a28eee402');
 /**
  * Each ed448/EdwardsPoint has 4 different equivalent points. This can be
  * a source of bugs for protocols like ring signatures. Decaf was created to solve this.
@@ -291,7 +399,7 @@ class _DecafPoint extends PrimeEdwardsPoint {
     // The following gymnastics is done because typescript strips comments otherwise
     // prettier-ignore
     static BASE = 
-    /* @__PURE__ */ (() => new _DecafPoint(ed448_Point.BASE).multiplyUnsafe(_2n))();
+    /* @__PURE__ */ (() => new _DecafPoint(new ed448_Point(DECAF_BASE_X, DECAF_BASE_Y, _1n, DECAF_BASE_T)))();
     // prettier-ignore
     static ZERO = 
     /* @__PURE__ */ (() => new _DecafPoint(ed448_Point.ZERO))();
@@ -304,6 +412,12 @@ class _DecafPoint extends PrimeEdwardsPoint {
     constructor(ep) {
         super(ep);
     }
+    /**
+     * Create one Decaf448 point from affine Edwards coordinates.
+     * This wraps the internal Edwards representative directly and is not a
+     * canonical decaf448 decoding path.
+     * Use `toBytes()` / `fromBytes()` if canonical decaf448 bytes matter.
+     */
     static fromAffine(ap) {
         return new _DecafPoint(ed448_Point.fromAffine(ap));
     }
@@ -341,7 +455,7 @@ class _DecafPoint extends PrimeEdwardsPoint {
     /**
      * Converts decaf-encoded string to decaf point.
      * Described in [RFC9496](https://www.rfc-editor.org/rfc/rfc9496#name-decode-2).
-     * @param hex Decaf-encoded 56 bytes. Not every 56-byte string is valid decaf encoding
+     * @param hex - Decaf-encoded 56 bytes. Not every 56-byte string is valid decaf encoding
      */
     static fromHex(hex) {
         return _DecafPoint.fromBytes(hexToBytes(hex));
@@ -381,12 +495,29 @@ class _DecafPoint extends PrimeEdwardsPoint {
         return this.equals(_DecafPoint.ZERO);
     }
 }
-export const decaf448 = { Point: _DecafPoint };
-/** Hashing to decaf448 points / field. RFC 9380 methods. */
-export const decaf448_hasher = {
+Object.freeze(_DecafPoint.BASE);
+Object.freeze(_DecafPoint.ZERO);
+Object.freeze(_DecafPoint.prototype);
+Object.freeze(_DecafPoint);
+/** Prime-order Decaf448 group bundle. */
+export const decaf448 = /* @__PURE__ */ Object.freeze({ Point: _DecafPoint });
+/**
+ * Hashing to decaf448 points / field. RFC 9380 methods.
+ * `hashToCurve()` is RFC 9380 `hash_to_decaf448`, `deriveToCurve()` is RFC
+ * 9496 element derivation, and `hashToScalar()` is a library helper layered on
+ * top of RFC 9496 scalar reduction.
+ * @example
+ * Hash one message onto decaf448.
+ *
+ * ```ts
+ * const point = decaf448_hasher.hashToCurve(new TextEncoder().encode('hello noble'));
+ * ```
+ */
+export const decaf448_hasher = Object.freeze({
     Point: _DecafPoint,
     hashToCurve(msg, options) {
-        const DST = options?.DST || 'decaf448_XOF:SHAKE256_D448MAP_RO_';
+        // Preserve explicit empty/invalid DST overrides so expand_message_xof() can reject them.
+        const DST = options?.DST === undefined ? 'decaf448_XOF:SHAKE256_D448MAP_RO_' : options.DST;
         return decaf448_hasher.deriveToCurve(expand_message_xof(msg, DST, 112, 224, shake256));
     },
     /**
@@ -403,8 +534,10 @@ export const decaf448_hasher = {
      * HashToCurve-like construction based on RFC 9496 (Element Derivation).
      * Converts 112 uniform random bytes into a curve point.
      *
-     * WARNING: This represents an older hash-to-curve construction, preceding the finalization of RFC 9380.
-     * It was later reused as a component in the newer `hash_to_ristretto255` function defined in RFC 9380.
+     * WARNING: This represents an older hash-to-curve construction from before
+     * RFC 9380 was finalized.
+     * It was later reused as a component in the newer
+     * `hash_to_decaf448` function defined in RFC 9380.
      */
     deriveToCurve(bytes) {
         abytes(bytes, 112);
@@ -418,9 +551,21 @@ export const decaf448_hasher = {
         const R2 = calcElligatorDecafMap(r2);
         return new _DecafPoint(R1.add(R2));
     },
-};
-/** decaf448 OPRF, defined in RFC 9497. */
-export const decaf448_oprf = /* @__PURE__ */ (() => createORPF({
+});
+/**
+ * decaf448 OPRF, defined in RFC 9497.
+ * @example
+ * Run one blind/evaluate/finalize OPRF round over decaf448.
+ *
+ * ```ts
+ * const input = new TextEncoder().encode('hello noble');
+ * const keys = decaf448_oprf.oprf.generateKeyPair();
+ * const blind = decaf448_oprf.oprf.blind(input);
+ * const evaluated = decaf448_oprf.oprf.blindEvaluate(keys.secretKey, blind.blinded);
+ * const output = decaf448_oprf.oprf.finalize(input, blind.blind, evaluated);
+ * ```
+ */
+export const decaf448_oprf = /* @__PURE__ */ (() => createOPRF({
     name: 'decaf448-SHAKE256',
     Point: _DecafPoint,
     hash: (msg) => shake256(msg, { dkLen: 64 }),
@@ -430,13 +575,20 @@ export const decaf448_oprf = /* @__PURE__ */ (() => createORPF({
 /**
  * Weird / bogus points, useful for debugging.
  * Unlike ed25519, there is no ed448 generator point which can produce full T subgroup.
- * Instead, there is a Klein four-group, which spans over 2 independent 2-torsion points:
- * (0, 1), (0, -1), (-1, 0), (1, 0).
+ * Instead, the torsion subgroup here is cyclic of order 4, generated by
+ * `(1, 0)`, and the array below lists that subgroup set (Klein four-group).
+ * @example
+ * Decode one known torsion point for debugging.
+ *
+ * ```ts
+ * import { ED448_TORSION_SUBGROUP, ed448 } from '@noble/curves/ed448.js';
+ * const point = ed448.Point.fromHex(ED448_TORSION_SUBGROUP[1]);
+ * ```
  */
-export const ED448_TORSION_SUBGROUP = [
+export const ED448_TORSION_SUBGROUP = /* @__PURE__ */ Object.freeze([
     '010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
     'fefffffffffffffffffffffffffffffffffffffffffffffffffffffffeffffffffffffffffffffffffffffffffffffffffffffffffffffff00',
     '000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
     '000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000080',
-];
+]);
 //# sourceMappingURL=ed448.js.map