@noble/curves 2.0.1 → 2.2.0

package/src/misc.ts

@@ -4,10 +4,10 @@
  * @module
  */
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
-import { blake256 } from '@noble/hashes/blake1.js';
+import { blake512 } from '@noble/hashes/blake1.js';
 import { blake2s } from '@noble/hashes/blake2.js';
 import { sha256, sha384, sha512 } from '@noble/hashes/sha2.js';
-import { concatBytes } from '@noble/hashes/utils.js';
+import { abytes, concatBytes } from '@noble/hashes/utils.js';
 import {
   eddsa,
   edwards,
@@ -16,12 +16,14 @@ import {
   type EdwardsPoint,
 } from './abstract/edwards.ts';
 import { ecdsa, weierstrass, type ECDSA, type WeierstrassOpts } from './abstract/weierstrass.ts';
-import { asciiToBytes } from './utils.ts';
+import { asciiToBytes, type TArg } from './utils.ts';
 
 // Jubjub curves have 𝔽p over scalar fields of other curves. They are friendly to ZK proofs.
 
-// jubjub p = bls n, verify in bls12-381.ts
-const jubjub_CURVE: EdwardsOpts = {
+// Zcash Protocol Specification "Jubjub" parameters:
+// q = BLS12-381 Fr, r, h = 8, a = -1, d = -10240/10241.
+// Gx/Gy keep the canonical Jubjub base point used by Zcash implementations.
+const jubjub_CURVE: EdwardsOpts = /* @__PURE__ */ (() => ({
   p: BigInt('0x73eda753299d7d483339d80809a1d80553bda402fffe5bfeffffffff00000001'),
   n: BigInt('0xe7db4ea6533afa906673b0101343b00a6682093ccc81082d0970e5ed6f72cb7'),
   h: BigInt(8),
@@ -29,29 +31,88 @@ const jubjub_CURVE: EdwardsOpts = {
   d: BigInt('0x2a9318e74bfa2b48f5fd9207e6bd7fd4292d7f6d37579d2601065fd6d6343eb1'),
   Gx: BigInt('0x11dafe5d23e1218086a365b99fbf3d3be72f6afd7d1f72623e6b071492d1122b'),
   Gy: BigInt('0x1d523cf1ddab1a1793132e78c866c0c33e26ba5cc220fed7cc3f870e59d292aa'),
-};
-/** Curve over scalar field of bls12-381. jubjub Fp = bls n */
-export const jubjub: EdDSA = /* @__PURE__ */ eddsa(edwards(jubjub_CURVE), sha512);
+}))();
+/**
+ * Generic EdDSA-over-Jubjub convenience wrapper with `sha512`.
+ * This is not the Zcash RedJubjub / Sapling signature scheme.
+ * @example
+ * Generate one Jubjub keypair, sign a message, and verify it.
+ *
+ * ```ts
+ * const { secretKey, publicKey } = jubjub.keygen();
+ * const msg = new TextEncoder().encode('hello noble');
+ * const sig = jubjub.sign(msg, secretKey);
+ * const isValid = jubjub.verify(sig, msg, publicKey);
+ * ```
+ */
+export const jubjub: EdDSA = /* @__PURE__ */ (() => eddsa(edwards(jubjub_CURVE), sha512))();
 
-// babyjubjub p = bn254 n, verify in bn254.ts
-const babyjubjub_CURVE: EdwardsOpts = {
+// BabyJubJub over bn254 Fr. EIP-2494 explicitly defines both the full-group generator G and the
+// prime-order subgroup base point B = 8*G.
+// noble's Edwards abstraction expects Point.BASE / curve.n to describe the prime-order subgroup, so
+// use the EIP base point B here.
+// Historical noble incorrectly used the EIP generator G as Point.BASE, which mismatched the
+// abstraction and leaked the wrong order into consumers.
+// Historical noble used G instead:
+//   Gx = 995203441582195749578291179787384436505546430278305826713579947235728471134
+//   Gy = 5472060717959818805561601436314318772137091100104008585924551046643952123905
+const babyjubjub_CURVE: EdwardsOpts = /* @__PURE__ */ (() => ({
   p: BigInt('0x30644e72e131a029b85045b68181585d2833e84879b9709143e1f593f0000001'),
-  n: BigInt('0x30644e72e131a029b85045b68181585d59f76dc1c90770533b94bee1c9093788'),
+  n: BigInt('0x060c89ce5c263405370a08b6d0302b0bab3eedb83920ee0a677297dc392126f1'),
   h: BigInt(8),
   a: BigInt('168700'),
   d: BigInt('168696'),
-  Gx: BigInt('0x23343e3445b673d38bcba38f25645adb494b1255b1162bb40f41a59f4d4b45e'),
-  Gy: BigInt('0xc19139cb84c680a6e14116da06056174a0cfa121e6e5c2450f87d64fc000001'),
-};
-/** Curve over scalar field of bn254. babyjubjub Fp = bn254 n */
-export const babyjubjub: EdDSA = /* @__PURE__ */ eddsa(edwards(babyjubjub_CURVE), blake256);
+  Gx: BigInt('0xbb77a6ad63e739b4eacb2e09d6277c12ab8d8010534e0b62893f3f6bb957051'),
+  Gy: BigInt('0x25797203f7a0b24925572e1cd16bf9edfce0051fb9e133774b3c257a872d7d8b'),
+}))();
+/**
+ * Curve over scalar field of bn254. babyjubjub Fp = bn254 n
+ * This is a working generic EdDSA-over-BabyJubJub wrapper that uses `blake512` for the 64-byte
+ * secret expansion required by the shared EdDSA helper.
+ * It is not the BabyJubJub stack used by iden3/circomlib, `babyjubjub-rs`, or
+ * `@zk-kit/eddsa-poseidon`: those pair the subgroup base B/B8 with Blake-style secret expansion
+ * plus dedicated Poseidon / MiMC / Pedersen transcript hashing. This wrapper stays generic and is
+ * not meant as an interoperability target for those BabyJubJub signing stacks.
+ * @example
+ * Access the BabyJubJub base point and round-trip it through the point codec.
+ *
+ * ```ts
+ * import { babyjubjub } from '@noble/curves/misc.js';
+ * const base = babyjubjub.Point.BASE;
+ * const encoded = base.toBytes();
+ * const decoded = babyjubjub.Point.fromBytes(encoded);
+ * ```
+ */
+export const babyjubjub: EdDSA = /* @__PURE__ */ (() =>
+  eddsa(edwards(babyjubjub_CURVE), blake512))();
 
-const jubjub_gh_first_block = asciiToBytes(
+// Sapling URS randomness beacon from the Zcash protocol. This stays as the 64-byte ASCII
+// lowercase-hex string used for the first Blake2s block, not 32 raw bytes.
+const jubjub_gh_first_block = /* @__PURE__ */ asciiToBytes(
   '096b36a5804bfacef1691e173c366a47ff5ba84a44f26ddd7e8d9f79d5b42df0'
 );
 
-// Returns point at JubJub curve which is prime order and not zero
-export function jubjub_groupHash(tag: Uint8Array, personalization: Uint8Array): EdwardsPoint {
+/**
+ * @param tag - Hash input.
+ * @param personalization - BLAKE2 personalization bytes.
+ * @returns Prime-order Jubjub point.
+ * @throws If the digest does not decode to a Jubjub point, or if the
+ *   cofactor-cleared point has small order. {@link Error}
+ * @example
+ * Hash a tag into a prime-order Jubjub point.
+ *
+ * ```ts
+ * import { jubjub_groupHash } from '@noble/curves/misc.js';
+ * import { asciiToBytes } from '@noble/curves/utils.js';
+ * const tag = Uint8Array.of(2);
+ * const personalization = asciiToBytes('Zcash_G_');
+ * const point = jubjub_groupHash(tag, personalization);
+ * ```
+ */
+export function jubjub_groupHash(
+  tag: TArg<Uint8Array>,
+  personalization: TArg<Uint8Array>
+): EdwardsPoint {
   const h = blake2s.create({ personalization, dkLen: 32 });
   h.update(jubjub_gh_first_block);
   h.update(tag);
@@ -63,10 +124,32 @@ export function jubjub_groupHash(tag: Uint8Array, personalization: Uint8Array):
   return p;
 }
 
-// No secret data is leaked here at all.
-// It operates over public data:
-// const G_SPEND = jubjub.findGroupHash(Uint8Array.of(), asciiToBytes('Item_G_'));
-export function jubjub_findGroupHash(m: Uint8Array, personalization: Uint8Array): EdwardsPoint {
+/**
+ * No secret data is leaked here at all.
+ * It operates over public data.
+ * @param m - Message prefix.
+ * @param personalization - 8-byte BLAKE2 personalization bytes.
+ * @returns First non-zero group hash.
+ * @throws If the personalization is invalid, or if no non-zero Jubjub group
+ *   hash can be found. {@link Error}
+ * @example
+ * Derive the first non-zero Jubjub group hash for one personalization tag.
+ *
+ * ```ts
+ * import { jubjub_findGroupHash } from '@noble/curves/misc.js';
+ * import { asciiToBytes } from '@noble/curves/utils.js';
+ * const msg = Uint8Array.of();
+ * const personalization = asciiToBytes('Zcash_G_');
+ * const point = jubjub_findGroupHash(msg, personalization);
+ * ```
+ */
+export function jubjub_findGroupHash(
+  m: TArg<Uint8Array>,
+  personalization: TArg<Uint8Array>
+): EdwardsPoint {
+  // Validate BLAKE2s personalization once up front; otherwise the retry loop swallows the real
+  // input error and turns it into a misleading "tag overflow".
+  abytes(personalization, 8, 'personalization');
   const tag = concatBytes(m, Uint8Array.of(0));
   const hashes = [];
   for (let i = 0; i < 256; i++) {
@@ -79,7 +162,7 @@ export function jubjub_findGroupHash(m: Uint8Array, personalization: Uint8Array)
   return hashes[0];
 }
 
-const brainpoolP256r1_CURVE: WeierstrassOpts<bigint> = {
+const brainpoolP256r1_CURVE: WeierstrassOpts<bigint> = /* @__PURE__ */ (() => ({
   p: BigInt('0xa9fb57dba1eea9bc3e660a909d838d726e3bf623d52620282013481d1f6e5377'),
   a: BigInt('0x7d5a0975fc2c3057eef67530417affe7fb8055c126dc5c6ce94a4b44f330b5d9'),
   b: BigInt('0x26dc5c6ce94a4b44f330b5d9bbd77cbf958416295cf7e1ce6bccdc18ff8c07b6'),
@@ -87,11 +170,23 @@ const brainpoolP256r1_CURVE: WeierstrassOpts<bigint> = {
   Gx: BigInt('0x8bd2aeb9cb7e57cb2c4b482ffc81b7afb9de27e1e3bd23c23a4453bd9ace3262'),
   Gy: BigInt('0x547ef835c3dac4fd97f8461a14611dc9c27745132ded8e545c1d54c72f046997'),
   h: BigInt(1),
-};
-/** Brainpool P256r1 with sha256, from RFC 5639. */
-export const brainpoolP256r1: ECDSA = ecdsa(weierstrass(brainpoolP256r1_CURVE), sha256);
+}))();
+/**
+ * Brainpool P256r1 with sha256, from RFC 5639.
+ * @example
+ * Generate one Brainpool P256r1 keypair, sign a message, and verify it.
+ *
+ * ```ts
+ * const { secretKey, publicKey } = brainpoolP256r1.keygen();
+ * const msg = new TextEncoder().encode('hello noble');
+ * const sig = brainpoolP256r1.sign(msg, secretKey);
+ * const isValid = brainpoolP256r1.verify(sig, msg, publicKey);
+ * ```
+ */
+export const brainpoolP256r1: ECDSA = /* @__PURE__ */ (() =>
+  ecdsa(weierstrass(brainpoolP256r1_CURVE), sha256))();
 
-const brainpoolP384r1_CURVE: WeierstrassOpts<bigint> = {
+const brainpoolP384r1_CURVE: WeierstrassOpts<bigint> = /* @__PURE__ */ (() => ({
   p: BigInt(
     '0x8cb91e82a3386d280f5d6f7e50e641df152f7109ed5456b412b1da197fb71123acd3a729901d1a71874700133107ec53'
   ),
@@ -111,11 +206,23 @@ const brainpoolP384r1_CURVE: WeierstrassOpts<bigint> = {
     '0x8abe1d7520f9c2a45cb1eb8e95cfd55262b70b29feec5864e19c054ff99129280e4646217791811142820341263c5315'
   ),
   h: BigInt(1),
-};
-/** Brainpool P384r1 with sha384, from RFC 5639. */
-export const brainpoolP384r1: ECDSA = ecdsa(weierstrass(brainpoolP384r1_CURVE), sha384);
+}))();
+/**
+ * Brainpool P384r1 with sha384, from RFC 5639.
+ * @example
+ * Generate one Brainpool P384r1 keypair, sign a message, and verify it.
+ *
+ * ```ts
+ * const { secretKey, publicKey } = brainpoolP384r1.keygen();
+ * const msg = new TextEncoder().encode('hello noble');
+ * const sig = brainpoolP384r1.sign(msg, secretKey);
+ * const isValid = brainpoolP384r1.verify(sig, msg, publicKey);
+ * ```
+ */
+export const brainpoolP384r1: ECDSA = /* @__PURE__ */ (() =>
+  ecdsa(weierstrass(brainpoolP384r1_CURVE), sha384))();
 
-const brainpoolP512r1_CURVE: WeierstrassOpts<bigint> = {
+const brainpoolP512r1_CURVE: WeierstrassOpts<bigint> = /* @__PURE__ */ (() => ({
   p: BigInt(
     '0xaadd9db8dbe9c48b3fd4e6ae33c9fc07cb308db3b3c9d20ed6639cca703308717d4d9b009bc66842aecda12ae6a380e62881ff2f2d82c68528aa6056583a48f3'
   ),
@@ -135,6 +242,18 @@ const brainpoolP512r1_CURVE: WeierstrassOpts<bigint> = {
     '0x7dde385d566332ecc0eabfa9cf7822fdf209f70024a57b1aa000c55b881f8111b2dcde494a5f485e5bca4bd88a2763aed1ca2b2fa8f0540678cd1e0f3ad80892'
   ),
   h: BigInt(1),
-};
-/** Brainpool P521r1 with sha512, from RFC 5639. */
-export const brainpoolP512r1: ECDSA = ecdsa(weierstrass(brainpoolP512r1_CURVE), sha512);
+}))();
+/**
+ * Brainpool P512r1 with sha512, from RFC 5639.
+ * @example
+ * Generate one Brainpool P512r1 keypair, sign a message, and verify it.
+ *
+ * ```ts
+ * const { secretKey, publicKey } = brainpoolP512r1.keygen();
+ * const msg = new TextEncoder().encode('hello noble');
+ * const sig = brainpoolP512r1.sign(msg, secretKey);
+ * const isValid = brainpoolP512r1.verify(sig, msg, publicKey);
+ * ```
+ */
+export const brainpoolP512r1: ECDSA = /* @__PURE__ */ (() =>
+  ecdsa(weierstrass(brainpoolP512r1_CURVE), sha512))();

package/src/nist.ts

@@ -5,9 +5,9 @@
  */
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
 import { sha256, sha384, sha512 } from '@noble/hashes/sha2.js';
+import { createFROST, type FROST } from './abstract/frost.ts';
 import { createHasher, type H2CHasher } from './abstract/hash-to-curve.ts';
-import { Field } from './abstract/modular.ts';
-import { createORPF, type OPRF } from './abstract/oprf.ts';
+import { createOPRF, type OPRF } from './abstract/oprf.ts';
 import {
   ecdsa,
   mapToCurveSimpleSWU,
@@ -16,6 +16,7 @@ import {
   type WeierstrassOpts,
   type WeierstrassPointCons,
 } from './abstract/weierstrass.ts';
+import { type TRet } from './utils.ts';
 
 // p = 2n**224n * (2n**32n-1n) + 2n**192n + 2n**96n - 1n
 // a = Fp256.create(BigInt('-3'));
@@ -82,8 +83,11 @@ type SwuOpts = {
 };
 
 function createSWU(Point: WeierstrassPointCons<bigint>, opts: SwuOpts) {
-  const map = mapToCurveSimpleSWU(Point.Fp, opts);
-  return (scalars: bigint[]) => map(scalars[0]);
+  let map: ((u: bigint) => { x: bigint; y: bigint }) | undefined;
+  // RFC 9380's NIST suites here all use m = 1, so createHasher passes one field element per map.
+  // Building the SWU sqrt-ratio helper eagerly adds noticeable `nist.js` import cost, so defer it
+  // to first use; after that the cached mapper is reused directly.
+  return (scalars: bigint[]) => (map || (map = mapToCurveSimpleSWU(Point.Fp, opts)))(scalars[0]);
 }
 
 // NIST P256
@@ -93,6 +97,8 @@ const p256_Point = /* @__PURE__ */ weierstrass(p256_CURVE);
  * Hashes inputs with sha256 by default.
  *
  * @example
+ * Generate one P-256 keypair, sign a message, and verify it.
+ *
  * ```js
  * import { p256 } from '@noble/curves/nist.js';
  * const { secretKey, publicKey } = p256.keygen();
@@ -104,7 +110,15 @@ const p256_Point = /* @__PURE__ */ weierstrass(p256_CURVE);
  * ```
  */
 export const p256: ECDSA = /* @__PURE__ */ ecdsa(p256_Point, sha256);
-/** Hashing / encoding to p256 points / field. RFC 9380 methods. */
+/**
+ * Hashing / encoding to p256 points / field. RFC 9380 methods.
+ * @example
+ * Hash one message onto the P-256 curve.
+ *
+ * ```ts
+ * const point = p256_hasher.hashToCurve(new TextEncoder().encode('hello noble'));
+ * ```
+ */
 export const p256_hasher: H2CHasher<WeierstrassPointCons<bigint>> = /* @__PURE__ */ (() => {
   return createHasher(
     p256_Point,
@@ -124,21 +138,71 @@ export const p256_hasher: H2CHasher<WeierstrassPointCons<bigint>> = /* @__PURE__
     }
   );
 })();
-/** p256 OPRF, defined in RFC 9497. */
-export const p256_oprf: OPRF = /* @__PURE__ */ (() =>
-  createORPF({
+/**
+ * p256 OPRF, defined in RFC 9497.
+ * @example
+ * Run one blind/evaluate/finalize OPRF round over P-256.
+ *
+ * ```ts
+ * const input = new TextEncoder().encode('hello noble');
+ * const keys = p256_oprf.oprf.generateKeyPair();
+ * const blind = p256_oprf.oprf.blind(input);
+ * const evaluated = p256_oprf.oprf.blindEvaluate(keys.secretKey, blind.blinded);
+ * const output = p256_oprf.oprf.finalize(input, blind.blind, evaluated);
+ * ```
+ */
+export const p256_oprf: TRet<OPRF> = /* @__PURE__ */ (() =>
+  createOPRF({
     name: 'P256-SHA256',
     Point: p256_Point,
     hash: sha256,
     hashToGroup: p256_hasher.hashToCurve,
     hashToScalar: p256_hasher.hashToScalar,
   }))();
+/**
+ * FROST threshold signatures over p256. RFC 9591.
+ * @example
+ * Create one trusted-dealer package for 2-of-3 p256 signing.
+ *
+ * ```ts
+ * const alice = p256_FROST.Identifier.derive('alice@example.com');
+ * const bob = p256_FROST.Identifier.derive('bob@example.com');
+ * const carol = p256_FROST.Identifier.derive('carol@example.com');
+ * const deal = p256_FROST.trustedDealer({ min: 2, max: 3 }, [alice, bob, carol]);
+ * ```
+ */
+export const p256_FROST: TRet<FROST> = /* @__PURE__ */ (() =>
+  createFROST({
+    name: 'FROST-P256-SHA256-v1',
+    Point: p256_Point,
+    hashToScalar: p256_hasher.hashToScalar,
+    hash: sha256,
+  }))();
 
 // NIST P384
 const p384_Point = /* @__PURE__ */ weierstrass(p384_CURVE);
-/** NIST P384 (aka secp384r1) curve, ECDSA and ECDH methods. Hashes inputs with sha384 by default. */
+/**
+ * NIST P384 (aka secp384r1) curve, ECDSA and ECDH methods. Hashes inputs with sha384 by default.
+ * @example
+ * Generate one P-384 keypair, sign a message, and verify it.
+ *
+ * ```ts
+ * const { secretKey, publicKey } = p384.keygen();
+ * const msg = new TextEncoder().encode('hello noble');
+ * const sig = p384.sign(msg, secretKey);
+ * const isValid = p384.verify(sig, msg, publicKey);
+ * ```
+ */
 export const p384: ECDSA = /* @__PURE__ */ ecdsa(p384_Point, sha384);
-/** Hashing / encoding to p384 points / field. RFC 9380 methods. */
+/**
+ * Hashing / encoding to p384 points / field. RFC 9380 methods.
+ * @example
+ * Hash one message onto the P-384 curve.
+ *
+ * ```ts
+ * const point = p384_hasher.hashToCurve(new TextEncoder().encode('hello noble'));
+ * ```
+ */
 export const p384_hasher: H2CHasher<WeierstrassPointCons<bigint>> = /* @__PURE__ */ (() => {
   return createHasher(
     p384_Point,
@@ -158,9 +222,21 @@ export const p384_hasher: H2CHasher<WeierstrassPointCons<bigint>> = /* @__PURE__
     }
   );
 })();
-/** p384 OPRF, defined in RFC 9497. */
-export const p384_oprf: OPRF = /* @__PURE__ */ (() =>
-  createORPF({
+/**
+ * p384 OPRF, defined in RFC 9497.
+ * @example
+ * Run one blind/evaluate/finalize OPRF round over P-384.
+ *
+ * ```ts
+ * const input = new TextEncoder().encode('hello noble');
+ * const keys = p384_oprf.oprf.generateKeyPair();
+ * const blind = p384_oprf.oprf.blind(input);
+ * const evaluated = p384_oprf.oprf.blindEvaluate(keys.secretKey, blind.blinded);
+ * const output = p384_oprf.oprf.finalize(input, blind.blind, evaluated);
+ * ```
+ */
+export const p384_oprf: TRet<OPRF> = /* @__PURE__ */ (() =>
+  createOPRF({
     name: 'P384-SHA384',
     Point: p384_Point,
     hash: sha384,
@@ -169,11 +245,46 @@ export const p384_oprf: OPRF = /* @__PURE__ */ (() =>
   }))();
 
 // NIST P521
-const Fn521 = /* @__PURE__ */ (() => Field(p521_CURVE.n, { allowedLengths: [65, 66] }))();
-const p521_Point = /* @__PURE__ */ weierstrass(p521_CURVE, { Fn: Fn521 });
-/** NIST P521 (aka secp521r1) curve, ECDSA and ECDH methods. Hashes inputs with sha512 by default. */
+// RFC 7518 fixes the canonical JWK/JOSE width at 66 bytes:
+// - Section 3.4 says ECDSA octet strings must not omit leading zero octets
+// - Sections 6.2.1.2/6.2.1.3 say P-521 coordinates "x"/"y" must be 66 octets
+// - Section 6.2.2.1 says private scalar "d" must be ceil(log2(n)/8) octets, i.e. 66 for P-521
+// NIST FIPS 186-5 Appendix A.3.3 also routes deterministic ECDSA private keys through Appendix
+// B.2.3, whose Integer-to-Octet-String output has explicit fixed length L; for P-521 that is the
+// same 66-byte order width.
+// RFC 6979 matches that width too: private key x is an integer, while `int2octets(x)` uses
+// rlen = 8 * ceil(qlen/8); for P-521, qlen = 521 so the canonical octet width is 66 bytes.
+// Wycheproof ECDH stores private values as integers, not fixed-width scalar bytes, so it does not
+// require a dedicated 65-byte parser path; the repo tests now normalize those integer fixtures to
+// the canonical 66-byte width before use. There is no good standards or oracle reason to accept
+// exactly 65 bytes here: the coherent choices are canonical 66 only, or a broader integer-style
+// parser across many widths. Since this field parser is fixed-width, keep it canonical and use the
+// default exact-66-byte scalar field path.
+const p521_Point = /* @__PURE__ */ weierstrass(p521_CURVE);
+/**
+ * NIST P521 (aka secp521r1) curve, ECDSA and ECDH methods. Hashes inputs with sha512 by default.
+ * Deterministic `keygen(seed)` expects 99 seed bytes here because the generic scalar-derivation
+ * helper uses `getMinHashLength(n)`, not the 66-byte canonical secret-key width.
+ * @example
+ * Generate one P-521 keypair, sign a message, and verify it.
+ *
+ * ```ts
+ * const { secretKey, publicKey } = p521.keygen();
+ * const msg = new TextEncoder().encode('hello noble');
+ * const sig = p521.sign(msg, secretKey);
+ * const isValid = p521.verify(sig, msg, publicKey);
+ * ```
+ */
 export const p521: ECDSA = /* @__PURE__ */ ecdsa(p521_Point, sha512);
-/** Hashing / encoding to p521 points / field. RFC 9380 methods. */
+/**
+ * Hashing / encoding to p521 points / field. RFC 9380 methods.
+ * @example
+ * Hash one message onto the P-521 curve.
+ *
+ * ```ts
+ * const point = p521_hasher.hashToCurve(new TextEncoder().encode('hello noble'));
+ * ```
+ */
 export const p521_hasher: H2CHasher<WeierstrassPointCons<bigint>> = /* @__PURE__ */ (() => {
   return createHasher(
     p521_Point,
@@ -193,9 +304,21 @@ export const p521_hasher: H2CHasher<WeierstrassPointCons<bigint>> = /* @__PURE__
     }
   );
 })();
-/** p521 OPRF, defined in RFC 9497. */
-export const p521_oprf: OPRF = /* @__PURE__ */ (() =>
-  createORPF({
+/**
+ * p521 OPRF, defined in RFC 9497.
+ * @example
+ * Run one blind/evaluate/finalize OPRF round over P-521.
+ *
+ * ```ts
+ * const input = new TextEncoder().encode('hello noble');
+ * const keys = p521_oprf.oprf.generateKeyPair();
+ * const blind = p521_oprf.oprf.blind(input);
+ * const evaluated = p521_oprf.oprf.blindEvaluate(keys.secretKey, blind.blinded);
+ * const output = p521_oprf.oprf.finalize(input, blind.blind, evaluated);
+ * ```
+ */
+export const p521_oprf: TRet<OPRF> = /* @__PURE__ */ (() =>
+  createOPRF({
     name: 'P521-SHA512',
     Point: p521_Point,
     hash: sha512,