@noble/curves 1.1.0 → 1.3.0

package/README.md

@@ -2,33 +2,29 @@
 
 Audited & minimal JS implementation of elliptic curve cryptography.
 
-- 🔒 [**Audited**](#security) by an independent security firm
+- 🔒 [**Audited**](#security) by independent security firms
 - 🔻 Tree-shaking-friendly: use only what's necessary, other code won't be included
 - 🏎 Ultra-fast, hand-optimized for caveats of JS engines
 - 🔍 Unique tests ensure correctness: property-based, cross-library and Wycheproof vectors, fuzzing
 - ➰ Short Weierstrass, Edwards, Montgomery curves
 - ✍️ ECDSA, EdDSA, Schnorr, BLS signature schemes, ECDH key agreement
-- 🔖 SUF-CMA and SBS (non-repudiation) for ed25519, ed448 and others
-- #️⃣ Hash-to-curve
-  for encoding or hashing an arbitrary string to an elliptic curve point
+- 🔖 SUF-CMA, SBS (non-repudiation), ZIP215 (consensus friendliness) features for ed25519
+- #️⃣ hash-to-curve for encoding or hashing an arbitrary string to an elliptic curve point
 - 🧜‍♂️ Poseidon ZK-friendly hash
 
-Check out [Upgrading](#upgrading) if you've previously used single-feature noble
-packages. See [Resources](#resources) for articles and real-world software that uses curves.
-
 ### This library belongs to _noble_ crypto
 
 > **noble-crypto** — high-security, easily auditable set of contained cryptographic libraries and tools.
 
-- No dependencies, protection against supply chain attacks
-- Auditable TypeScript / JS code
-- Supported in all major browsers and stable node.js versions
-- All releases are signed with PGP keys
-- Check out [homepage](https://paulmillr.com/noble/) & all libraries:
-  [curves](https://github.com/paulmillr/noble-curves)
-  (4kb versions [secp256k1](https://github.com/paulmillr/noble-secp256k1),
-  [ed25519](https://github.com/paulmillr/noble-ed25519)),
+- Zero or minimal dependencies
+- Highly readable TypeScript / JS code
+- PGP-signed releases and transparent NPM builds
+- All libraries:
+  [ciphers](https://github.com/paulmillr/noble-ciphers),
+  [curves](https://github.com/paulmillr/noble-curves),
   [hashes](https://github.com/paulmillr/noble-hashes)
+- [Check out homepage](https://paulmillr.com/noble/)
+  for reading resources, documentation and apps built with noble
 
 ## Usage
 
@@ -36,36 +32,56 @@ packages. See [Resources](#resources) for articles and real-world software that
 
 We support all major platforms and runtimes.
 For [Deno](https://deno.land), ensure to use [npm specifier](https://deno.land/manual@v1.28.0/node/npm_specifiers).
-For React Native, you may need a [polyfill for crypto.getRandomValues](https://github.com/LinusU/react-native-get-random-values).
-If you don't like NPM, a standalone [noble-curves.js](https://github.com/paulmillr/noble-curves/releases) is also available.
-
-The library is tree-shaking-friendly and does not expose root entry point as
-`@noble/curves`. Instead, you need to import specific primitives.
-This is done to ensure small size of your apps.
+For React Native, you may need a [polyfill for getRandomValues](https://github.com/LinusU/react-native-get-random-values).
+A standalone file [noble-curves.js](https://github.com/paulmillr/noble-curves/releases) is also available.
 
-The package consists of two parts:
+```js
+// import * from '@noble/curves'; // Error: use sub-imports, to ensure small app size
+import { secp256k1 } from '@noble/curves/secp256k1'; // ESM and Common.js
+// import { secp256k1 } from 'npm:@noble/curves@1.2.0/secp256k1'; // Deno
+```
 
-* [Implementations](#implementations), utilizing one dependency [noble-hashes](https://github.com/paulmillr/noble-hashes),
-   providing ready-to-use:
-   - NIST curves secp256r1 / p256, secp384r1 / p384, secp521r1 / p521
-   - SECG curve secp256k1
-   - ed25519 / curve25519 / x25519 / ristretto255, edwards448 / curve448 / x448
-   - pairing-friendly curves bls12-381, bn254
-   - [pasta](https://electriccoin.co/blog/the-pasta-curves-for-halo-2-and-beyond/) curves
-2. [Abstract](#abstract-api), zero-dependency elliptic curve algorithms
+- [Implementations](#implementations)
+  - [ECDSA signature scheme](#ecdsa-signature-scheme)
+  - [ECDSA public key recovery & extra entropy](#ecdsa-public-key-recovery--extra-entropy)
+  - [ECDH: Elliptic Curve Diffie-Hellman](#ecdh-elliptic-curve-diffie-hellman)
+  - [Schnorr signatures over secp256k1, BIP340](#schnorr-signatures-over-secp256k1-bip340)
+  - [ed25519, X25519, ristretto255](#ed25519-x25519-ristretto255)
+  - [ed448, X448, decaf448](#ed448-x448-decaf448)
+  - [bls12-381](#bls12-381)
+  - [All available imports](#all-available-imports)
+  - [Accessing a curve's variables](#accessing-a-curves-variables)
+- [Abstract API](#abstract-api)
+  - [weierstrass: Short Weierstrass curve](#weierstrass-short-weierstrass-curve)
+  - [edwards: Twisted Edwards curve](#edwards-twisted-edwards-curve)
+  - [montgomery: Montgomery curve](#montgomery-montgomery-curve)
+  - [bls: Barreto-Lynn-Scott curves](#bls-barreto-lynn-scott-curves)
+  - [hash-to-curve: Hashing strings to curve points](#hash-to-curve-hashing-strings-to-curve-points)
+  - [poseidon: Poseidon hash](#poseidon-poseidon-hash)
+  - [modular: Modular arithmetics utilities](#modular-modular-arithmetics-utilities)
+    - [Creating private keys from hashes](#creating-private-keys-from-hashes)
+  - [utils: Useful utilities](#utils-useful-utilities)
+- [Security](#security)
+- [Speed](#speed)
+- [Upgrading](#upgrading)
+- [Contributing & testing](#contributing--testing)
+- [Resources](#resources)
 
 ### Implementations
 
-#### Generic example for all curves, secp256k1
+Implementations use [noble-hashes](https://github.com/paulmillr/noble-hashes).
+If you want to use a different hashing library, [abstract API](#abstract-api) doesn't depend on them.
+
+#### ECDSA signature scheme
+
+Generic example that works for all curves, shown for secp256k1:
 
 ```ts
-// Each curve has similar methods
-import { secp256k1 } from '@noble/curves/secp256k1'; // ESM and Common.js
-// import { secp256k1 } from 'npm:@noble/curves@1.2.0/secp256k1'; // Deno
+import { secp256k1 } from '@noble/curves/secp256k1';
 const priv = secp256k1.utils.randomPrivateKey();
 const pub = secp256k1.getPublicKey(priv);
-const msg = new Uint8Array(32).fill(1);
-const sig = secp256k1.sign(msg, priv);
+const msg = new Uint8Array(32).fill(1); // message hash (not message) in ecdsa
+const sig = secp256k1.sign(msg, priv); // `{prehash: true}` option is available
 const isValid = secp256k1.verify(sig, msg, pub) === true;
 
 // hex strings are also supported besides Uint8Arrays:
@@ -73,29 +89,24 @@ const privHex = '46c930bc7bb4db7f55da20798697421b98c4175a52c630294d75a84b9c12623
 const pub2 = secp256k1.getPublicKey(privHex);
 ```
 
-#### All imports
+#### ECDSA public key recovery & extra entropy
 
-```typescript
-import { secp256k1, schnorr } from '@noble/curves/secp256k1';
-import { ed25519, ed25519ph, ed25519ctx, x25519, RistrettoPoint } from '@noble/curves/ed25519';
-import { ed448, ed448ph, ed448ctx, x448 } from '@noble/curves/ed448';
-import { p256 } from '@noble/curves/p256';
-import { p384 } from '@noble/curves/p384';
-import { p521 } from '@noble/curves/p521';
-import { pallas, vesta } from '@noble/curves/pasta';
-import { bls12_381 } from '@noble/curves/bls12-381';
-import { bn254 } from '@noble/curves/bn254';
-import { jubjub } from '@noble/curves/jubjub';
+```ts
+// let sig = secp256k1.Signature.fromCompact(sigHex); // or .fromDER(sigDERHex)
+// sig = sig.addRecoveryBit(bit); // bit is not serialized into compact / der format
+sig.recoverPublicKey(msg).toRawBytes(); // === pub; // public key recovery
+
+// extraEntropy https://moderncrypto.org/mail-archive/curves/2017/000925.html
+const sigImprovedSecurity = secp256k1.sign(msg, priv, { extraEntropy: true });
 ```
 
-#### ECDSA public key recovery & ECDH
+#### ECDH: Elliptic Curve Diffie-Hellman
 
 ```ts
-// extraEntropy https://moderncrypto.org/mail-archive/curves/2017/000925.html
-const sigImprovedSecurity = secp256k1.sign(msg, priv, { extraEntropy: true });
-sig.recoverPublicKey(msg) === pub; // public key recovery
+// 1. The output includes parity byte. Strip it using shared.slice(1)
+// 2. The output is not hashed. More secure way is sha256(shared) or hkdf(shared)
 const someonesPub = secp256k1.getPublicKey(secp256k1.utils.randomPrivateKey());
-const shared = secp256k1.getSharedSecret(priv, someonesPub); // ECDH
+const shared = secp256k1.getSharedSecret(priv, someonesPub);
 ```
 
 #### Schnorr signatures over secp256k1 (BIP340)
@@ -129,7 +140,6 @@ It has SUF-CMA (strong unforgeability under chosen message attacks).
 and additionally provides non-repudiation with SBS [(Strongly Binding Signatures)](https://eprint.iacr.org/2020/1244).
 
 X25519 follows [RFC7748](https://www.rfc-editor.org/rfc/rfc7748).
-ristretto255 follows [irtf draft](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-ristretto255-decaf448).
 
 ```ts
 // Variants from RFC8032: with context, prehashed
@@ -147,17 +157,36 @@ x25519.getPublicKey(x25519.utils.randomPrivateKey());
 import { edwardsToMontgomeryPub, edwardsToMontgomeryPriv } from '@noble/curves/ed25519';
 edwardsToMontgomeryPub(ed25519.getPublicKey(ed25519.utils.randomPrivateKey()));
 edwardsToMontgomeryPriv(ed25519.utils.randomPrivateKey());
+```
 
+ristretto255 follows [irtf draft](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-ristretto255-decaf448).
+
+```ts
 // hash-to-curve, ristretto255
-import { hashToCurve, encodeToCurve, RistrettoPoint } from '@noble/curves/ed25519';
+import { utf8ToBytes } from '@noble/hashes/utils';
+import { sha512 } from '@noble/hashes/sha512';
+import {
+  hashToCurve,
+  encodeToCurve,
+  RistrettoPoint,
+  hashToRistretto255,
+} from '@noble/curves/ed25519';
+
+const msg = utf8ToBytes('Ristretto is traditionally a short shot of espresso coffee');
+hashToCurve(msg);
+
 const rp = RistrettoPoint.fromHex(
   '6a493210f7499cd17fecb510ae0cea23a110e8d5b901f8acadd3095c73a3b919'
 );
-RistrettoPoint.hashToCurve('Ristretto is traditionally a short shot of espresso coffee');
-// also has add(), equals(), multiply(), toRawBytes() methods
+RistrettoPoint.BASE.multiply(2n).add(rp).subtract(RistrettoPoint.BASE).toRawBytes();
+RistrettoPoint.ZERO.equals(dp) === false;
+// pre-hashed hash-to-curve
+RistrettoPoint.hashToCurve(sha512(msg));
+// full hash-to-curve including domain separation tag
+hashToRistretto255(msg, { DST: 'ristretto255_XMD:SHA-512_R255MAP_RO_' });
 ```
 
-#### ed448, X448
+#### ed448, X448, decaf448
 
 ```ts
 import { ed448 } from '@noble/curves/ed448';
@@ -167,17 +196,65 @@ const msg = new TextEncoder().encode('whatsup');
 const sig = ed448.sign(msg, priv);
 ed448.verify(sig, msg, pub);
 
-import { ed448ph, ed448ctx, x448, hashToCurve, encodeToCurve } from '@noble/curves/ed448';
+// Variants from RFC8032: prehashed
+import { ed448ph } from '@noble/curves/ed448';
+```
+
+ECDH using Curve448 aka X448, follows [RFC7748](https://www.rfc-editor.org/rfc/rfc7748).
+
+```ts
+import { x448 } from '@noble/curves/ed448';
 x448.getSharedSecret(priv, pub) === x448.scalarMult(priv, pub); // aliases
 x448.getPublicKey(priv) === x448.scalarMultBase(priv);
+
+// ed448 => x448 conversion
+import { edwardsToMontgomeryPub } from '@noble/curves/ed448';
+edwardsToMontgomeryPub(ed448.getPublicKey(ed448.utils.randomPrivateKey()));
+```
+
+decaf448 follows [irtf draft](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-ristretto255-decaf448).
+
+```ts
+import { utf8ToBytes } from '@noble/hashes/utils';
+import { shake256 } from '@noble/hashes/sha3';
+import { hashToCurve, encodeToCurve, DecafPoint, hashToDecaf448 } from '@noble/curves/ed448';
+
+const msg = utf8ToBytes('Ristretto is traditionally a short shot of espresso coffee');
+hashToCurve(msg);
+
+const dp = DecafPoint.fromHex(
+  'c898eb4f87f97c564c6fd61fc7e49689314a1f818ec85eeb3bd5514ac816d38778f69ef347a89fca817e66defdedce178c7cc709b2116e75'
+);
+DecafPoint.BASE.multiply(2n).add(dp).subtract(DecafPoint.BASE).toRawBytes();
+DecafPoint.ZERO.equals(dp) === false;
+// pre-hashed hash-to-curve
+DecafPoint.hashToCurve(shake256(msg, { dkLen: 112 }));
+// full hash-to-curve including domain separation tag
+hashToDecaf448(msg, { DST: 'decaf448_XOF:SHAKE256_D448MAP_RO_' });
 ```
 
-Same RFC7748 / RFC8032 are followed.
+Same RFC7748 / RFC8032 / IRTF draft are followed.
 
 #### bls12-381
 
 See [abstract/bls](#abstractbls-barreto-lynn-scott-curves).
 
+#### All available imports
+
+```typescript
+import { secp256k1, schnorr } from '@noble/curves/secp256k1';
+import { ed25519, ed25519ph, ed25519ctx, x25519, RistrettoPoint } from '@noble/curves/ed25519';
+import { ed448, ed448ph, ed448ctx, x448 } from '@noble/curves/ed448';
+import { p256 } from '@noble/curves/p256';
+import { p384 } from '@noble/curves/p384';
+import { p521 } from '@noble/curves/p521';
+import { pallas, vesta } from '@noble/curves/pasta';
+import { bls12_381 } from '@noble/curves/bls12-381';
+import { bn254 } from '@noble/curves/bn254'; // also known as alt_bn128
+import { jubjub } from '@noble/curves/jubjub';
+import { bytesToHex, hexToBytes, concatBytes, utf8ToBytes } from '@noble/curves/abstract/utils';
+```
+
 #### Accessing a curve's variables
 
 ```ts
@@ -199,18 +276,7 @@ Precomputes are enabled for weierstrass and edwards BASE points of a curve. You
 could precompute any other point (e.g. for ECDH) using `utils.precompute()`
 method: check out examples.
 
-There are following zero-dependency algorithms:
-
-- [abstract/weierstrass: Short Weierstrass curve](#abstractweierstrass-short-weierstrass-curve)
-- [abstract/edwards: Twisted Edwards curve](#abstractedwards-twisted-edwards-curve)
-- [abstract/montgomery: Montgomery curve](#abstractmontgomery-montgomery-curve)
-- [abstract/bls: Barreto-Lynn-Scott curves](#abstractbls-barreto-lynn-scott-curves)
-- [abstract/hash-to-curve: Hashing strings to curve points](#abstracthash-to-curve-hashing-strings-to-curve-points)
-- [abstract/poseidon: Poseidon hash](#abstractposeidon-poseidon-hash)
-- [abstract/modular: Modular arithmetics utilities](#abstractmodular-modular-arithmetics-utilities)
-- [abstract/utils: General utilities](#abstractutils-general-utilities)
-
-### abstract/weierstrass: Short Weierstrass curve
+### weierstrass: Short Weierstrass curve
 
 ```ts
 import { weierstrass } from '@noble/curves/abstract/weierstrass';
@@ -233,7 +299,7 @@ const secq256k1 = weierstrass({
   randomBytes,
 });
 
-// Replace weierstrass with weierstrassPoints if you don't need ECDSA, hash, hmac, randomBytes
+// Replace weierstrass() with weierstrassPoints() if you don't need ECDSA, hash, hmac, randomBytes
 ```
 
 Short Weierstrass curve's formula is `y² = x³ + ax + b`. `weierstrass`
@@ -252,8 +318,17 @@ type CHash = {
   outputLen: number;
   create(): any;
 };
+
+// example
+function sha256(message: Uint8Array) { return _internal_lowlvl(message) }
+sha256.outputLen = 32; // 32 bytes of output for sha2-256
 ```
 
+**Message hash** is expected instead of message itself:
+
+- `sign(msgHash, privKey)` is default behavior, assuming you pre-hash msg with sha2, or other hash
+- `sign(msg, privKey, {prehash: true})` option can be used if you want to pass the message itself
+
 **Weierstrass points:**
 
 1. Exported as `ProjectivePoint`
@@ -349,6 +424,7 @@ More examples:
 const priv = secq256k1.utils.randomPrivateKey();
 secq256k1.getPublicKey(priv); // Convert private key to public.
 const sig = secq256k1.sign(msg, priv); // Sign msg with private key.
+const sig2 = secq256k1.sign(msg, priv, { prehash: true }); // hash(msg)
 secq256k1.verify(sig, msg, priv); // Verify if sig is correct.
 
 const Point = secq256k1.ProjectivePoint;
@@ -371,7 +447,7 @@ const fast = secq256k1.utils.precompute(8, Point.fromHex(someonesPubKey));
 fast.multiply(privKey); // much faster ECDH now
 ```
 
-### abstract/edwards: Twisted Edwards curve
+### edwards: Twisted Edwards curve
 
 ```ts
 import { twistedEdwards } from '@noble/curves/abstract/edwards';
@@ -461,7 +537,7 @@ interface ExtPointConstructor extends GroupConstructor<ExtPointType> {
 }
 ```
 
-### abstract/montgomery: Montgomery curve
+### montgomery: Montgomery curve
 
 ```typescript
 import { montgomery } from '@noble/curves/abstract/montgomery';
@@ -488,7 +564,7 @@ Proper Elliptic Curve Points are not implemented yet.
 
 You must specify curve params `Fp`, `a`, `Gu` coordinate of u, `montgomeryBits` and `nByteLength`.
 
-### abstract/bls: Barreto-Lynn-Scott curves
+### bls: Barreto-Lynn-Scott curves
 
 The module abstracts BLS (Barreto-Lynn-Scott) pairing-friendly elliptic curve construction.
 They allow to construct [zk-SNARKs](https://z.cash/technology/zksnarks/) and
@@ -496,6 +572,10 @@ use aggregated, batch-verifiable
 [threshold signatures](https://medium.com/snigirev.stepan/bls-signatures-better-than-schnorr-5a7fe30ea716),
 using Boneh-Lynn-Shacham signature scheme.
 
+The module doesn't expose `CURVE` property: use `G1.CURVE`, `G2.CURVE` instead.
+Only BLS12-381 is implemented currently.
+Defining BLS12-377 and BLS24 should be straightforward.
+
 Main methods and properties are:
 
 - `getPublicKey(privateKey)`
@@ -507,8 +587,13 @@ Main methods and properties are:
 - `Signature` property with `fromHex`, `toHex` methods
 - `fields` containing `Fp`, `Fp2`, `Fp6`, `Fp12`, `Fr`
 
-Right now we only implement BLS12-381 (compatible with ETH and others),
-but in theory defining BLS12-377, BLS24 should be straightforward. An example:
+The default BLS uses short public keys (with public keys in G1 and signatures in G2).
+Short signatures (public keys in G2 and signatures in G1) is also supported, using:
+
+- `getPublicKeyForShortSignatures(privateKey)`
+- `signShortSignature(message, privateKey)`
+- `verifyShortSignature(signature, message, publicKey)`
+- `aggregateShortSignatures(signatures)`
 
 ```ts
 import { bls12_381 as bls } from '@noble/curves/bls12-381';
@@ -539,66 +624,22 @@ const aggSignature3 = bls.aggregateSignatures(signatures3);
 const isValid3 = bls.verifyBatch(aggSignature3, messages, publicKeys);
 console.log({ publicKeys, signatures3, aggSignature3, isValid3 });
 
-// bls.pairing(PointG1, PointG2) // pairings
-// bls.G1.ProjectivePoint.BASE, bls.G2.ProjectivePoint.BASE
-// bls.fields.Fp, bls.fields.Fp2, bls.fields.Fp12, bls.fields.Fr
+// Pairings, with and without final exponentiation
+bls.pairing(PointG1, PointG2);
+bls.pairing(PointG1, PointG2, false);
+bls.fields.Fp12.finalExponentiate(bls.fields.Fp12.mul(PointG1, PointG2));
 
-// hash-to-curve examples can be seen below
-```
-
-Full types:
+// Others
+bls.G1.ProjectivePoint.BASE, bls.G2.ProjectivePoint.BASE
+bls.fields.Fp, bls.fields.Fp2, bls.fields.Fp12, bls.fields.Fr
+bls.params.x, bls.params.r, bls.params.G1b, bls.params.G2b
 
-```ts
-getPublicKey: (privateKey: PrivKey) => Uint8Array;
-sign: {
-  (message: Hex, privateKey: PrivKey): Uint8Array;
-  (message: ProjPointType<Fp2>, privateKey: PrivKey): ProjPointType<Fp2>;
-};
-verify: (
-  signature: Hex | ProjPointType<Fp2>,
-  message: Hex | ProjPointType<Fp2>,
-  publicKey: Hex | ProjPointType<Fp>
-) => boolean;
-verifyBatch: (
-  signature: Hex | ProjPointType<Fp2>,
-  messages: (Hex | ProjPointType<Fp2>)[],
-  publicKeys: (Hex | ProjPointType<Fp>)[]
-) => boolean;
-aggregatePublicKeys: {
-  (publicKeys: Hex[]): Uint8Array;
-  (publicKeys: ProjPointType<Fp>[]): ProjPointType<Fp>;
-};
-aggregateSignatures: {
-  (signatures: Hex[]): Uint8Array;
-  (signatures: ProjPointType<Fp2>[]): ProjPointType<Fp2>;
-};
-millerLoop: (ell: [Fp2, Fp2, Fp2][], g1: [Fp, Fp]) => Fp12;
-pairing: (P: ProjPointType<Fp>, Q: ProjPointType<Fp2>, withFinalExponent?: boolean) => Fp12;
-G1: CurvePointsRes<Fp> & ReturnType<typeof htf.createHasher<Fp>>;
-G2: CurvePointsRes<Fp2> & ReturnType<typeof htf.createHasher<Fp2>>;
-Signature: SignatureCoder<Fp2>;
-params: {
-  x: bigint;
-  r: bigint;
-  G1b: bigint;
-  G2b: Fp2;
-};
-fields: {
-  Fp: IField<Fp>;
-  Fp2: IField<Fp2>;
-  Fp6: IField<Fp6>;
-  Fp12: IField<Fp12>;
-  Fr: IField<bigint>;
-};
-utils: {
-  randomPrivateKey: () => Uint8Array;
-  calcPairingPrecomputes: (p: AffinePoint<Fp2>) => [Fp2, Fp2, Fp2][];
-};
+// hash-to-curve examples can be seen below
 ```
 
-### abstract/hash-to-curve: Hashing strings to curve points
+### hash-to-curve: Hashing strings to curve points
 
-The module allows to hash arbitrary strings to elliptic curve points. Implements [hash-to-curve v16](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hash-to-curve-16).
+The module allows to hash arbitrary strings to elliptic curve points. Implements [RFC 9380](https://www.rfc-editor.org/rfc/rfc9380).
 
 Every curve has exported `hashToCurve` and `encodeToCurve` methods. You should always prefer `hashToCurve` for security:
 
@@ -614,19 +655,17 @@ bls12_381.G1.hashToCurve(randomBytes(), { DST: 'another' });
 bls12_381.G2.hashToCurve(randomBytes(), { DST: 'custom' });
 ```
 
-If you need low-level methods from spec:
-
-`expand_message_xmd` [(spec)](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hash-to-curve-11#section-5.4.1) produces a uniformly random byte string using a cryptographic hash function H that outputs b bits.
-
-Hash must conform to `CHash` interface (see [weierstrass section](#abstractweierstrass-short-weierstrass-curve)).
+Low-level methods from the spec:
 
 ```ts
+// produces a uniformly random byte string using a cryptographic hash function H that outputs b bits.
 function expand_message_xmd(
   msg: Uint8Array,
   DST: Uint8Array,
   lenInBytes: number,
-  H: CHash
+  H: CHash // For CHash see abstract/weierstrass docs section
 ): Uint8Array;
+// produces a uniformly random byte string using an extendable-output function (XOF) H.
 function expand_message_xof(
   msg: Uint8Array,
   DST: Uint8Array,
@@ -634,13 +673,9 @@ function expand_message_xof(
   k: number,
   H: CHash
 ): Uint8Array;
-```
-
-`hash_to_field(msg, count, options)`
-[(spec)](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hash-to-curve-11#section-5.3)
-hashes arbitrary-length byte strings to a list of one or more elements of a finite field F.
+// Hashes arbitrary-length byte strings to a list of one or more elements of a finite field F
+function hash_to_field(msg: Uint8Array, count: number, options: Opts): bigint[][];
 
-```ts
 /**
  * * `DST` is a domain separation tag, defined in section 2.2.5
  * * `p` characteristic of F, where F is a finite field of characteristic p and order q = p^m
@@ -651,26 +686,16 @@ hashes arbitrary-length byte strings to a list of one or more elements of a fini
  */
 type UnicodeOrBytes = string | Uint8Array;
 type Opts = {
-    DST: UnicodeOrBytes;
-    p: bigint;
-    m: number;
-    k: number;
-    expand?: 'xmd' | 'xof';
-    hash: CHash;
+  DST: UnicodeOrBytes;
+  p: bigint;
+  m: number;
+  k: number;
+  expand?: 'xmd' | 'xof';
+  hash: CHash;
 };
-
-/**
- * Hashes arbitrary-length byte strings to a list of one or more elements of a finite field F
- * https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hash-to-curve-11#section-5.3
- * @param msg a byte string containing the message to hash
- * @param count the number of elements of F to output
- * @param options `{DST: string, p: bigint, m: number, k: number, expand: 'xmd' | 'xof', hash: H}`, see above
- * @returns [u_0, ..., u_(count - 1)], a list of field elements.
- */
-function hash_to_field(msg: Uint8Array, count: number, options: Opts): bigint[][];
 ```
 
-### abstract/poseidon: Poseidon hash
+### poseidon: Poseidon hash
 
 Implements [Poseidon](https://www.poseidon-hash.info) ZK-friendly hash.
 
@@ -694,7 +719,7 @@ type PoseidonOpts = {
 const instance = poseidon(opts: PoseidonOpts);
 ```
 
-### abstract/modular: Modular arithmetics utilities
+### modular: Modular arithmetics utilities
 
 ```ts
 import * as mod from '@noble/curves/abstract/modular';
@@ -710,30 +735,41 @@ mod.invert(17n, 10n); // invert(17) mod 10; modular multiplicative inverse
 mod.invertBatch([1n, 2n, 4n], 21n); // => [1n, 11n, 16n] in one inversion
 ```
 
-#### Creating private keys from hashes
+Field operations are not constant-time: they are using JS bigints, see [security](#security).
+The fact is mostly irrelevant, but the important method to keep in mind is `pow`,
+which may leak exponent bits, when used naïvely.
+
+`mod.Field` is always **field over prime**. Non-prime fields aren't supported for now.
+We don't test for prime-ness for speed and because algorithms are probabilistic anyway.
+Initializing a non-prime field could make your app suspectible to
+DoS (infilite loop) on Tonelli-Shanks square root calculation.
+
+Unlike `mod.invert`, `mod.invertBatch` won't throw on `0`: make sure to throw an error yourself.
 
-Suppose you have `sha256(something)` (e.g. from HMAC) and you want to make a private key from it.
-Even though p256 or secp256k1 may have 32-byte private keys,
-and sha256 output is also 32-byte, you can't just use it and reduce it modulo `CURVE.n`.
+#### Creating private keys from hashes
 
-Doing so will make the result key [biased](https://research.kudelskisecurity.com/2020/07/28/the-definitive-guide-to-modulo-bias-and-how-to-avoid-it/).
+You can't simply make a 32-byte private key from a 32-byte hash.
+Doing so will make the key [biased](https://research.kudelskisecurity.com/2020/07/28/the-definitive-guide-to-modulo-bias-and-how-to-avoid-it/).
 
-To avoid the bias, we implement FIPS 186 B.4.1, which allows to take arbitrary
-byte array and produce valid scalars / private keys with bias being neglible.
+To make the bias negligible, we follow [FIPS 186-5 A.2](https://csrc.nist.gov/publications/detail/fips/186/5/final)
+and [RFC 9380](https://www.rfc-editor.org/rfc/rfc9380#section-5.2).
+This means, for 32-byte key, we would need 48-byte hash to get 2^-128 bias, which matches curve security level.
 
-Use [hash-to-curve](#abstracthash-to-curve-hashing-strings-to-curve-points) if you need
-hashing to **public keys**; the function in the module instead operates on **private keys**.
+`hashToPrivateScalar()` that hashes to **private key** was created for this purpose.
+Use [abstract/hash-to-curve](#abstracthash-to-curve-hashing-strings-to-curve-points)
+if you need to hash to **public key**.
 
 ```ts
 import { p256 } from '@noble/curves/p256';
 import { sha256 } from '@noble/hashes/sha256';
 import { hkdf } from '@noble/hashes/hkdf';
+import * as mod from '@noble/curves/abstract/modular';
 const someKey = new Uint8Array(32).fill(2); // Needs to actually be random, not .fill(2)
-const derived = hkdf(sha256, someKey, undefined, 'application', 40); // 40 bytes
+const derived = hkdf(sha256, someKey, undefined, 'application', 48); // 48 bytes for 32-byte priv
 const validPrivateKey = mod.hashToPrivateScalar(derived, p256.CURVE.n);
 ```
 
-### abstract/utils: General utilities
+### utils: Useful utilities
 
 ```ts
 import * as utils from '@noble/curves/abstract/utils';
@@ -755,25 +791,61 @@ utils.equalBytes(Uint8Array.from([0xde]), Uint8Array.from([0xde]));
 
 ## Security
 
-1. The library has been audited in Feb 2023 by an independent security firm [Trail of Bits](https://www.trailofbits.com):
-[PDF](https://github.com/trailofbits/publications/blob/master/reviews/2023-01-ryanshea-noblecurveslibrary-securityreview.pdf).
-The audit has been funded by [Ryan Shea](https://www.shea.io). Audit scope was abstract modules `curve`, `hash-to-curve`, `modular`, `poseidon`, `utils`, `weierstrass`, and top-level modules `_shortw_utils` and `secp256k1`. See [changes since audit](https://github.com/paulmillr/noble-curves/compare/0.7.3..main).
-2. The library has been fuzzed by [Guido Vranken's cryptofuzz](https://github.com/guidovranken/cryptofuzz). You can run the fuzzer by yourself to check it.
-3. [Timing attack](https://en.wikipedia.org/wiki/Timing_attack) considerations: _JIT-compiler_ and _Garbage Collector_ make "constant time" extremely hard to achieve in a scripting language. Which means _any other JS library can't have constant-timeness_. Even statically typed Rust, a language without GC, [makes it harder to achieve constant-time](https://www.chosenplaintext.ca/open-source/rust-timing-shield/security) for some cases. If your goal is absolute security, don't use any JS lib — including bindings to native ones. Use low-level libraries & languages. Nonetheless we're targetting algorithmic constant time.
-
-We consider infrastructure attacks like rogue NPM modules very important; that's why it's crucial to minimize the amount of 3rd-party dependencies & native bindings. If your app uses 500 dependencies, any dep could get hacked and you'll be downloading malware with every `npm install`. Our goal is to minimize this attack vector. As for devDependencies used by the library:
-
-- `@scure` base, bip32, bip39 (used in tests), micro-bmark (benchmark), micro-should (testing) are developed by us
-  and follow the same practices such as: minimal library size, auditability, signed releases
-- prettier (linter), fast-check (property-based testing),
-  typescript versions are locked and rarely updated. Every update is checked with `npm-diff`.
-  The packages are big, which makes it hard to audit their source code thoroughly and fully.
-- They are only used if you clone the git repo and want to add some feature to it. End-users won't use them.
-
-As for key generation, we're deferring to built-in
+The library has been independently audited:
+
+- at version 1.2.0, in Sep 2023, by [Kudelski Security](https://kudelskisecurity.com)
+  - PDFs: [offline](./audit/2023-09-kudelski-audit-starknet.pdf)
+  - [Changes since audit](https://github.com/paulmillr/noble-curves/compare/1.2.0..main)
+  - Scope: [scure-starknet](https://github.com/paulmillr/scure-starknet) and its related
+    abstract modules of noble-curves: `curve`, `modular`, `poseidon`, `weierstrass`
+  - The audit has been funded by [Starkware](https://starkware.co)
+- at version 0.7.3, in Feb 2023, by [Trail of Bits](https://www.trailofbits.com)
+  - PDFs: [online](https://github.com/trailofbits/publications/blob/master/reviews/2023-01-ryanshea-noblecurveslibrary-securityreview.pdf),
+    [offline](./audit/2023-01-trailofbits-audit-curves.pdf)
+  - [Changes since audit](https://github.com/paulmillr/noble-curves/compare/0.7.3..main)
+  - Scope: abstract modules `curve`, `hash-to-curve`, `modular`, `poseidon`, `utils`, `weierstrass` and
+    top-level modules `_shortw_utils` and `secp256k1`
+  - The audit has been funded by [Ryan Shea](https://www.shea.io)
+
+It is tested against property-based, cross-library and Wycheproof vectors,
+and has fuzzing by [Guido Vranken's cryptofuzz](https://github.com/guidovranken/cryptofuzz).
+
+If you see anything unusual: investigate and report.
+
+### Constant-timeness
+
+_JIT-compiler_ and _Garbage Collector_ make "constant time" extremely hard to
+achieve [timing attack](https://en.wikipedia.org/wiki/Timing_attack) resistance
+in a scripting language. Which means _any other JS library can't have
+constant-timeness_. Even statically typed Rust, a language without GC,
+[makes it harder to achieve constant-time](https://www.chosenplaintext.ca/open-source/rust-timing-shield/security)
+for some cases. If your goal is absolute security, don't use any JS lib — including bindings to native ones.
+Use low-level libraries & languages. Nonetheless we're targetting algorithmic constant time.
+
+### Supply chain security
+
+* **Commits** are signed with PGP keys, to prevent forgery. Make sure to verify commit signatures.
+* **Releases** are transparent and built on GitHub CI. Make sure to verify [provenance](https://docs.npmjs.com/generating-provenance-statements) logs
+* **Rare releasing** is followed to ensure less re-audit need for end-users
+* **Dependencies** are minimized and locked-down:
+   - If your app has 500 dependencies, any dep could get hacked and you'll be downloading
+     malware with every install. We make sure to use as few dependencies as possible
+   - We prevent automatic dependency updates by locking-down version ranges. Every update is checked with `npm-diff`
+   - One dependency [noble-hashes](https://github.com/paulmillr/noble-hashes) is used, by the same author, to provide hashing functionality
+* **Dev Dependencies** are only used if you want to contribute to the repo. They are disabled for end-users:
+   - scure-base, scure-bip32, scure-bip39, micro-bmark and micro-should are developed by the same author and follow identical security practices
+   - prettier (linter), fast-check (property-based testing) and typescript are used for code quality, vector generation and ts compilation. The packages are big, which makes it hard to audit their source code thoroughly and fully
+
+### Randomness
+
+We're deferring to built-in
 [crypto.getRandomValues](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues)
 which is considered cryptographically secure (CSPRNG).
 
+In the past, browsers had bugs that made it weak: it may happen again.
+Implementing a userspace CSPRNG to get resilient to the weakness
+is even worse: there is no reliable userspace source of quality entropy.
+
 ## Speed
 
 Benchmark results on Apple M2 with node v20:
@@ -855,45 +927,41 @@ ed25519 x 3,088 ops/sec @ 323μs/op
 ed448 x 1,247 ops/sec @ 801μs/op
 ```
 
-## Contributing & testing
-
-1. Clone the repository
-2. `npm install` to install build dependencies like TypeScript
-3. `npm run build` to compile TypeScript code
-4. `npm run test` will execute all main tests
-
 ## Upgrading
 
 Previously, the library was split into single-feature packages
-noble-secp256k1, noble-ed25519 and noble-bls12-381.
+[noble-secp256k1](https://github.com/paulmillr/noble-secp256k1),
+[noble-ed25519](https://github.com/paulmillr/noble-ed25519) and
+[noble-bls12-381](https://github.com/paulmillr/noble-bls12-381).
 
 Curves continue their original work. The single-feature packages changed their
 direction towards providing minimal 4kb implementations of cryptography,
 which means they have less features.
 
-Upgrading from @noble/secp256k1 2.0 or @noble/ed25519 2.0: no changes, libraries are compatible.
+Upgrading from noble-secp256k1 2.0 or noble-ed25519 2.0: no changes, libraries are compatible.
 
-Upgrading from [@noble/secp256k1](https://github.com/paulmillr/noble-secp256k1) 1.7:
+Upgrading from noble-secp256k1 1.7:
 
 - `getPublicKey`
-    - now produce 33-byte compressed signatures by default
-    - to use old behavior, which produced 65-byte uncompressed keys, set
-      argument `isCompressed` to `false`: `getPublicKey(priv, false)`
+  - now produce 33-byte compressed signatures by default
+  - to use old behavior, which produced 65-byte uncompressed keys, set
+    argument `isCompressed` to `false`: `getPublicKey(priv, false)`
 - `sign`
-    - is now sync; use `signAsync` for async version
-    - now returns `Signature` instance with `{ r, s, recovery }` properties
-    - `canonical` option was renamed to `lowS`
-    - `recovered` option has been removed because recovery bit is always returned now
-    - `der` option has been removed. There are 2 options:
-        1. Use compact encoding: `fromCompact`, `toCompactRawBytes`, `toCompactHex`.
-           Compact encoding is simply a concatenation of 32-byte r and 32-byte s.
-        2. If you must use DER encoding, switch to noble-curves (see above).
+  - is now sync
+  - now returns `Signature` instance with `{ r, s, recovery }` properties
+  - `canonical` option was renamed to `lowS`
+  - `recovered` option has been removed because recovery bit is always returned now
+  - `der` option has been removed. There are 2 options:
+    1. Use compact encoding: `fromCompact`, `toCompactRawBytes`, `toCompactHex`.
+       Compact encoding is simply a concatenation of 32-byte r and 32-byte s.
+    2. If you must use DER encoding, switch to noble-curves (see above).
 - `verify`
-    - `strict` option was renamed to `lowS`
+  - is now sync
+  - `strict` option was renamed to `lowS`
 - `getSharedSecret`
-    - now produce 33-byte compressed signatures by default
-    - to use old behavior, which produced 65-byte uncompressed keys, set
-      argument `isCompressed` to `false`: `getSharedSecret(a, b, false)`
+  - now produce 33-byte compressed signatures by default
+  - to use old behavior, which produced 65-byte uncompressed keys, set
+    argument `isCompressed` to `false`: `getSharedSecret(a, b, false)`
 - `recoverPublicKey(msg, sig, rec)` was changed to `sig.recoverPublicKey(msg)`
 - `number` type for private keys have been removed: use `bigint` instead
 - `Point` (2d xy) has been changed to `ProjectivePoint` (3d xyz)
@@ -914,53 +982,22 @@ Upgrading from [@noble/ed25519](https://github.com/paulmillr/noble-ed25519) 1.7:
 Upgrading from [@noble/bls12-381](https://github.com/paulmillr/noble-bls12-381):
 
 - Methods and classes were renamed:
-    - PointG1 -> G1.Point, PointG2 -> G2.Point
-    - PointG2.fromSignature -> Signature.decode, PointG2.toSignature ->  Signature.encode
+  - PointG1 -> G1.Point, PointG2 -> G2.Point
+  - PointG2.fromSignature -> Signature.decode, PointG2.toSignature -> Signature.encode
 - Fp2 ORDER was corrected
 
+## Contributing & testing
+
+1. Clone the repository
+2. `npm install` to install build dependencies like TypeScript
+3. `npm run build` to compile TypeScript code
+4. `npm run test` will execute all main tests
+
 ## Resources
 
-Useful documentation and articles about the library or its primitives:
-
-- [Learning fast elliptic-curve cryptography](https://paulmillr.com/posts/noble-secp256k1-fast-ecc/)
-- [Taming the many EdDSAs](https://csrc.nist.gov/csrc/media/Presentations/2023/crclub-2023-03-08/images-media/20230308-crypto-club-slides--taming-the-many-EdDSAs.pdf)
-  that describes concepts of Strong UnForgeability under Chosen Message Attacks and Strongly Binding Signatures
-- Pairings and BLS
-    - [BLS signatures for busy people](https://gist.github.com/paulmillr/18b802ad219b1aee34d773d08ec26ca2)
-    - [BLS12-381 for the rest of us](https://hackmd.io/@benjaminion/bls12-381)
-    - [Key concepts of pairings](https://medium.com/@alonmuroch_65570/bls-signatures-part-2-key-concepts-of-pairings-27a8a9533d0c)
-    - Pairing over bls12-381:
-      [part 1](https://research.nccgroup.com/2020/07/06/pairing-over-bls12-381-part-1-fields/),
-      [part 2](https://research.nccgroup.com/2020/07/13/pairing-over-bls12-381-part-2-curves/),
-      [part 3](https://research.nccgroup.com/2020/08/13/pairing-over-bls12-381-part-3-pairing/)
-    - [Estimating the bit security of pairing-friendly curves](https://research.nccgroup.com/2022/02/03/estimating-the-bit-security-of-pairing-friendly-curves/)
-
-Online demos:
-
-- [Elliptic Curve Calculator](https://paulmillr.com/noble): add / multiply points, sign messages
-- [BLS threshold signatures](https://genthresh.com)
-
-Projects using noble-curves:
-
-- [scure-bip32](https://github.com/paulmillr/scure-bip32) and separate [bip32](https://github.com/bitcoinjs/bip32) HDkey libraries
-- Ethereum libraries:
-    - [ethereum-cryptography](https://github.com/ethereum/js-ethereum-cryptography)
-    - [@ethereumjs](https://github.com/ethereumjs/ethereumjs-monorepo)
-    - [micro-eth-signer](https://github.com/paulmillr/micro-eth-signer)
-    - [ethers](https://github.com/ethers-io/ethers.js) (old noble-secp256k1 for now)
-    - [viem.sh](https://viem.sh)
-    - [metamask's eth-sig-util](https://github.com/MetaMask/eth-sig-util)
-    - [gridplus lattice sdk](https://github.com/GridPlus/lattice-eth2-utils)
-- Bitcoin libraries: [scure-btc-signer](https://github.com/paulmillr/scure-btc-signer)
-- Solana libraries: [micro-sol-signer](https://github.com/paulmillr/micro-sol-signer), [solana-web3.js](https://github.com/solana-labs/solana-web3.js)
-- [polkadot.js](https://github.com/polkadot-js/common), [micro-starknet](https://github.com/paulmillr/micro-starknet)
-- [protonmail](https://github.com/ProtonMail/WebClients) (old noble-ed25519 for now)
-- [did-jwt](https://github.com/decentralized-identity/did-jwt), [hpke-js](https://github.com/dajiaji/hpke-js), [nostr-tools](https://github.com/nbd-wtf/nostr-tools)
-- [ed25519-keygen](https://github.com/paulmillr/ed25519-keygen) SSH, PGP, TOR key generation
-- [secp256k1 compatibility layer](https://github.com/ethereum/js-ethereum-cryptography/blob/2.0.0/src/secp256k1-compat.ts)
-for users who want to switch from secp256k1-node or tiny-secp256k1. Allows to see which methods map to corresponding noble code.
-- [BLS BBS signatures](https://github.com/Wind4Greg/BBS-Draft-Checks) following [draft-irtf-cfrg-bbs-signatures-latest](https://identity.foundation/bbs-signature/draft-irtf-cfrg-bbs-signatures.html)
-- [KZG trusted setup ceremony](https://github.com/dsrvlabs/czg-keremony)
+Check out [paulmillr.com/noble](https://paulmillr.com/noble/)
+for useful resources, articles, documentation and demos
+related to the library.
 
 ## License