@noble/curves 0.8.2 → 0.9.0

package/README.md

@@ -1,28 +1,21 @@
 # noble-curves
 
-[Audited](#security) & minimal JS implementation of elliptic curve cryptography.
+Audited & minimal JS implementation of elliptic curve cryptography.
 
-- **noble** family, zero dependencies
 - Short Weierstrass, Edwards, Montgomery curves
 - ECDSA, EdDSA, Schnorr, BLS signature schemes, ECDH key agreement
+- 🔒 [**Audited**](#security) by an independent security firm
 - #️⃣ [hash to curve](#abstracthash-to-curve-hashing-strings-to-curve-points)
   for encoding or hashing an arbitrary string to an elliptic curve point
 - 🧜‍♂️ [Poseidon](https://www.poseidon-hash.info) ZK-friendly hash
 - 🏎 [Ultra-fast](#speed), hand-optimized for caveats of JS engines
-- 🔍 Unique tests ensure correctness with Wycheproof vectors and [cryptofuzz](https://github.com/guidovranken/cryptofuzz) differential fuzzing
-- 🔻 Tree-shaking-friendly: there is no entry point, which ensures small size of your app
+- 🔍 Unique tests ensure correctness with Wycheproof vectors and
+  [cryptofuzz](https://github.com/guidovranken/cryptofuzz) differential fuzzing
+- 🔻 Tree-shaking-friendly: use only what's necessary, other code won't be included
 
-Package consists of two parts:
-
-1. [Abstract](#abstract-api), zero-dependency EC algorithms
-2. [Implementations](#implementations), utilizing one dependency `@noble/hashes`, providing ready-to-use:
-   - NIST curves secp256r1/P256, secp384r1/P384, secp521r1/P521
-   - SECG curve secp256k1
-   - ed25519/curve25519/x25519/ristretto255, edwards448/curve448/x448 [RFC7748](https://www.rfc-editor.org/rfc/rfc7748) / [RFC8032](https://www.rfc-editor.org/rfc/rfc8032) / [ZIP215](https://zips.z.cash/zip-0215) stuff
-   - pairing-friendly curves bls12-381, bn254
-
-Check out [Upgrading](#upgrading) if you've previously used single-feature noble packages
-([secp256k1](https://github.com/paulmillr/noble-secp256k1), [ed25519](https://github.com/paulmillr/noble-ed25519)).
+Check out [Upgrading](#upgrading) if you've previously used single-feature noble
+packages ([secp256k1](https://github.com/paulmillr/noble-secp256k1),
+[ed25519](https://github.com/paulmillr/noble-ed25519)).
 See [Resources](#resources) for articles and real-world software that uses curves.
 
 ### This library belongs to _noble_ crypto
@@ -30,33 +23,50 @@ See [Resources](#resources) for articles and real-world software that uses curve
 > **noble-crypto** — high-security, easily auditable set of contained cryptographic libraries and tools.
 
 - No dependencies, protection against supply chain attacks
-- Easily auditable TypeScript/JS code
+- 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)
-  ([secp256k1](https://github.com/paulmillr/noble-secp256k1),
+  (4kb versions [secp256k1](https://github.com/paulmillr/noble-secp256k1),
   [ed25519](https://github.com/paulmillr/noble-ed25519)),
   [hashes](https://github.com/paulmillr/noble-hashes)
 
 ## Usage
 
-Use NPM for browser / node.js:
+Browser, deno and node.js are supported:
 
 > npm install @noble/curves
 
-For [Deno](https://deno.land), use it with [npm specifier](https://deno.land/manual@v1.28.0/node/npm_specifiers). In browser, you could also include the single file from
+For [Deno](https://deno.land), use it with
+[npm specifier](https://deno.land/manual@v1.28.0/node/npm_specifiers).
+In browser, you could also include the single file from
 [GitHub's releases page](https://github.com/paulmillr/noble-curves/releases).
 
-The library is tree-shaking-friendly and does not expose root entry point as `import * from '@noble/curves'`.
-Instead, you need to import specific primitives. This is done to ensure small size of your apps.
+The library is tree-shaking-friendly and does not expose root entry point as
+`import * from '@noble/curves'`. Instead, you need to import specific primitives.
+This is done to ensure small size of your apps.
+
+Package consists of two parts:
+
+1. [Implementations](#implementations), utilizing one dependency `@noble/hashes`,
+   providing ready-to-use:
+   - NIST curves secp256r1/P256, secp384r1/P384, secp521r1/P521
+   - SECG curve secp256k1
+   - ed25519/curve25519/x25519/ristretto255, edwards448/curve448/x448
+     implementing
+     [RFC7748](https://www.rfc-editor.org/rfc/rfc7748) /
+     [RFC8032](https://www.rfc-editor.org/rfc/rfc8032) /
+     [ZIP215](https://zips.z.cash/zip-0215) standards
+   - pairing-friendly curves bls12-381, bn254
+2. [Abstract](#abstract-api), zero-dependency EC algorithms
 
 ### Implementations
 
 Each curve can be used in the following way:
 
 ```ts
-import { secp256k1 } from '@noble/curves/secp256k1'; // ECMAScript Modules (ESM) and Common.js
+import { secp256k1 } from '@noble/curves/secp256k1'; // ESM and Common.js
 // import { secp256k1 } from 'npm:@noble/curves@1.2.0/secp256k1'; // Deno
 const priv = secp256k1.utils.randomPrivateKey();
 const pub = secp256k1.getPublicKey(priv);
@@ -64,8 +74,9 @@ const msg = new Uint8Array(32).fill(1);
 const sig = secp256k1.sign(msg, priv);
 secp256k1.verify(sig, msg, pub) === true;
 
+// hex strings are also supported besides Uint8Arrays:
 const privHex = '46c930bc7bb4db7f55da20798697421b98c4175a52c630294d75a84b9c126236';
-const pub2 = secp256k1.getPublicKey(privHex); // keys & other inputs can be Uint8Array-s or hex strings
+const pub2 = secp256k1.getPublicKey(privHex);
 ```
 
 All curves:
@@ -90,7 +101,7 @@ Weierstrass curves feature recovering public keys from signatures and ECDH key a
 const sigImprovedSecurity = secp256k1.sign(msg, priv, { extraEntropy: true });
 sig.recoverPublicKey(msg) === pub; // public key recovery
 const someonesPub = secp256k1.getPublicKey(secp256k1.utils.randomPrivateKey());
-const shared = secp256k1.getSharedSecret(priv, someonesPub); // ECDH (elliptic curve diffie-hellman)
+const shared = secp256k1.getSharedSecret(priv, someonesPub); // ECDH
 ```
 
 secp256k1 has schnorr signature implementation which follows
@@ -103,7 +114,6 @@ const pub = schnorr.getPublicKey(priv);
 const msg = new TextEncoder().encode('hello');
 const sig = schnorr.sign(msg, priv);
 const isValid = schnorr.verify(sig, msg, pub);
-console.log(isValid);
 ```
 
 ed25519 module has ed25519ctx / ed25519ph variants,
@@ -134,18 +144,27 @@ RistrettoPoint.hashToCurve('Ristretto is traditionally a short shot of espresso
 // also has add(), equals(), multiply(), toRawBytes() methods
 ```
 
-ed448 module is basically the same:
+ed448 is similar:
 
 ```ts
 import { ed448, ed448ph, ed448ctx, x448 } from '@noble/curves/ed448';
 import { hashToCurve, encodeToCurve } from '@noble/curves/ed448';
+ed448.getPublicKey(ed448.utils.randomPrivateKey());
+```
+
+Every curve has params:
+
+```ts
+import { secp256k1 } from '@noble/curves/secp256k1'; // ESM and Common.js
+console.log(secp256k1.CURVE.p, secp256k1.CURVE.n, secp256k1.CURVE.a, secp256k1.CURVE.b);
 ```
 
 BLS12-381 pairing-friendly Barreto-Lynn-Scott elliptic curve construction allows to
 construct [zk-SNARKs](https://z.cash/technology/zksnarks/) at the 128-bit security
 and use aggregated, batch-verifiable
 [threshold signatures](https://medium.com/snigirev.stepan/bls-signatures-better-than-schnorr-5a7fe30ea716),
-using Boneh-Lynn-Shacham signature scheme.
+using Boneh-Lynn-Shacham signature scheme. Compatible with ETH and others,
+just make sure to provide correct DST (domain separation tag argument).
 
 ```ts
 import { bls12_381 as bls } from '@noble/curves/bls12-381';
@@ -182,10 +201,13 @@ console.log({ publicKeys, signatures3, aggSignature3, isValid3 });
 
 ## Abstract API
 
-Abstract API allows to define custom curves. All arithmetics is done with JS bigints over finite fields,
-which is defined from `modular` sub-module. For scalar multiplication, we use [precomputed tables with w-ary non-adjacent form (wNAF)](https://paulmillr.com/posts/noble-secp256k1-fast-ecc/).
-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.
+Abstract API allows to define custom curves. All arithmetics is done with JS
+bigints over finite fields, which is defined from `modular` sub-module. For
+scalar multiplication, we use
+[precomputed tables with w-ary non-adjacent form (wNAF)](https://paulmillr.com/posts/noble-secp256k1-fast-ecc/).
+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:
 
@@ -201,14 +223,36 @@ There are following zero-dependency algorithms:
 
 ```ts
 import { weierstrass } from '@noble/curves/abstract/weierstrass';
+import { Field } from '@noble/curves/abstract/modular'; // finite field for mod arithmetics
+import { sha256 } from '@noble/hashes/sha256'; // 3rd-party sha256() of type utils.CHash
+import { hmac } from '@noble/hashes/hmac'; // 3rd-party hmac() that will accept sha256()
+import { concatBytes, randomBytes } from '@noble/hashes/utils'; // 3rd-party utilities
+const secq256k1 = weierstrass({
+  // secq256k1: cycle of secp256k1 with Fp/N flipped.
+  // https://personaelabs.org/posts/spartan-ecdsa
+  // https://zcash.github.io/halo2/background/curves.html#cycles-of-curves
+  a: 0n,
+  b: 7n,
+  Fp: Field(2n ** 256n - 432420386565659656852420866394968145599n),
+  n: 2n ** 256n - 2n ** 32n - 2n ** 9n - 2n ** 8n - 2n ** 7n - 2n ** 6n - 2n ** 4n - 1n,
+  Gx: 55066263022277343669578718895168534326250603453777594175500187360389116729240n,
+  Gy: 32670510020758816978083085130507043184471273380659243275938904335757337482424n,
+  hash: sha256,
+  hmac: (key: Uint8Array, ...msgs: Uint8Array[]) => hmac(sha256, key, concatBytes(...msgs)),
+  randomBytes,
+});
+
+// weierstrassPoints can also be used if you don't need ECDSA, hash, hmac, randomBytes
 ```
 
-Short Weierstrass curve's formula is `y² = x³ + ax + b`. `weierstrass` expects arguments `a`, `b`, field `Fp`, curve order `n`, cofactor `h`
+Short Weierstrass curve's formula is `y² = x³ + ax + b`. `weierstrass`
+expects arguments `a`, `b`, field `Fp`, curve order `n`, cofactor `h`
 and coordinates `Gx`, `Gy` of generator point.
 
-**`k` generation** is done deterministically, following [RFC6979](https://www.rfc-editor.org/rfc/rfc6979).
-For this you will need `hmac` & `hash`, which in our implementations is provided by noble-hashes.
-If you're using different hashing library, make sure to wrap it in the following interface:
+**`k` generation** is done deterministically, following
+[RFC6979](https://www.rfc-editor.org/rfc/rfc6979). For this you will need
+`hmac` & `hash`, which in our implementations is provided by noble-hashes. If
+you're using different hashing library, make sure to wrap it in the following interface:
 
 ```ts
 type CHash = {
@@ -224,11 +268,36 @@ type CHash = {
 1. Exported as `ProjectivePoint`
 2. Represented in projective (homogeneous) coordinates: (x, y, z) ∋ (x=x/z, y=y/z)
 3. Use complete exception-free formulas for addition and doubling
-4. Can be decoded/encoded from/to Uint8Array / hex strings using `ProjectivePoint.fromHex` and `ProjectivePoint#toRawBytes()`
+4. Can be decoded/encoded from/to Uint8Array / hex strings using
+   `ProjectivePoint.fromHex` and `ProjectivePoint#toRawBytes()`
 5. Have `assertValidity()` which checks for being on-curve
 6. Have `toAffine()` and `x` / `y` getters which convert to 2d xy affine coordinates
 
 ```ts
+// `weierstrassPoints()` returns `CURVE` and `ProjectivePoint`
+// `weierstrass()` returns `CurveFn`
+type SignOpts = { lowS?: boolean; prehash?: boolean; extraEntropy: boolean | Uint8Array };
+type CurveFn = {
+  CURVE: ReturnType<typeof validateOpts>;
+  getPublicKey: (privateKey: PrivKey, isCompressed?: boolean) => Uint8Array;
+  getSharedSecret: (privateA: PrivKey, publicB: Hex, isCompressed?: boolean) => Uint8Array;
+  sign: (msgHash: Hex, privKey: PrivKey, opts?: SignOpts) => SignatureType;
+  verify: (
+    signature: Hex | SignatureType,
+    msgHash: Hex,
+    publicKey: Hex,
+    opts?: { lowS?: boolean; prehash?: boolean }
+  ) => boolean;
+  ProjectivePoint: ProjectivePointConstructor;
+  Signature: SignatureConstructor;
+  utils: {
+    normPrivateKeyToScalar: (key: PrivKey) => bigint;
+    isValidPrivateKey(key: PrivKey): boolean;
+    randomPrivateKey: () => Uint8Array;
+    precompute: (windowSize?: number, point?: ProjPointType<bigint>) => ProjPointType<bigint>;
+  };
+};
+
 // T is usually bigint, but can be something else like complex numbers in BLS curves
 interface ProjPointType<T> extends Group<ProjPointType<T>> {
   readonly px: T;
@@ -254,7 +323,8 @@ interface ProjConstructor<T> extends GroupConstructor<ProjPointType<T>> {
 }
 ```
 
-**ECDSA signatures** are represented by `Signature` instances and can be described by the interface:
+**ECDSA signatures** are represented by `Signature` instances and can be
+described by the interface:
 
 ```ts
 interface SignatureType {
@@ -279,28 +349,9 @@ type SignatureConstructor = {
 };
 ```
 
-Example implementing [secq256k1](https://personaelabs.org/posts/spartan-ecdsa) (NOT secp256k1)
-[cycle](https://zcash.github.io/halo2/background/curves.html#cycles-of-curves) of secp256k1 with Fp/N flipped.
+More examples:
 
 ```typescript
-import { weierstrass } from '@noble/curves/abstract/weierstrass';
-import { Field } from '@noble/curves/abstract/modular'; // finite field, mod arithmetics done over it
-import { sha256 } from '@noble/hashes/sha256'; // 3rd-party sha256() of type utils.CHash, with blockLen/outputLen
-import { hmac } from '@noble/hashes/hmac'; // 3rd-party hmac() that will accept sha256()
-import { concatBytes, randomBytes } from '@noble/hashes/utils'; // 3rd-party utilities
-const secq256k1 = weierstrass({
-  // secq256k1: cycle of secp256k1 with Fp/N flipped.
-  a: 0n,
-  b: 7n,
-  Fp: Field(2n ** 256n - 432420386565659656852420866394968145599n),
-  n: 2n ** 256n - 2n ** 32n - 2n ** 9n - 2n ** 8n - 2n ** 7n - 2n ** 6n - 2n ** 4n - 1n,
-  Gx: 55066263022277343669578718895168534326250603453777594175500187360389116729240n,
-  Gy: 32670510020758816978083085130507043184471273380659243275938904335757337482424n,
-  hash: sha256,
-  hmac: (key: Uint8Array, ...msgs: Uint8Array[]) => hmac(sha256, key, concatBytes(...msgs)),
-  randomBytes,
-});
-
 // All curves expose same generic interface.
 const priv = secq256k1.utils.randomPrivateKey();
 secq256k1.getPublicKey(priv); // Convert private key to public.
@@ -318,6 +369,7 @@ point.assertValidity(); // Checks for being on-curve
 point.toAffine(); // Converts to 2d affine xy coordinates
 
 secq256k1.CURVE.n;
+secq256k1.CURVE.p;
 secq256k1.CURVE.Fp.mod();
 secq256k1.CURVE.hash();
 
@@ -326,84 +378,19 @@ const fast = secq256k1.utils.precompute(8, Point.fromHex(someonesPubKey));
 fast.multiply(privKey); // much faster ECDH now
 ```
 
-`weierstrass()` returns `CurveFn`:
-
-```ts
-type SignOpts = { lowS?: boolean; prehash?: boolean; extraEntropy: boolean | Uint8Array };
-type CurveFn = {
-  CURVE: ReturnType<typeof validateOpts>;
-  getPublicKey: (privateKey: PrivKey, isCompressed?: boolean) => Uint8Array;
-  getSharedSecret: (privateA: PrivKey, publicB: Hex, isCompressed?: boolean) => Uint8Array;
-  sign: (msgHash: Hex, privKey: PrivKey, opts?: SignOpts) => SignatureType;
-  verify: (
-    signature: Hex | SignatureType,
-    msgHash: Hex,
-    publicKey: Hex,
-    opts?: { lowS?: boolean; prehash?: boolean }
-  ) => boolean;
-  ProjectivePoint: ProjectivePointConstructor;
-  Signature: SignatureConstructor;
-  utils: {
-    normPrivateKeyToScalar: (key: PrivKey) => bigint;
-    isValidPrivateKey(key: PrivKey): boolean;
-    randomPrivateKey: () => Uint8Array;
-    precompute: (windowSize?: number, point?: ProjPointType<bigint>) => ProjPointType<bigint>;
-  };
-};
-```
-
 ### abstract/edwards: Twisted Edwards curve
 
-Twisted Edwards curve's formula is `ax² + y² = 1 + dx²y²`. You must specify `a`, `d`, field `Fp`, order `n`, cofactor `h`
-and coordinates `Gx`, `Gy` of generator point.
-
-For EdDSA signatures, `hash` param required. `adjustScalarBytes` which instructs how to change private scalars could be specified.
-
-**Edwards points:**
-
-1. Exported as `ExtendedPoint`
-2. Represented in extended coordinates: (x, y, z, t) ∋ (x=x/z, y=y/z)
-3. Use complete exception-free formulas for addition and doubling
-4. Can be decoded/encoded from/to Uint8Array / hex strings using `ExtendedPoint.fromHex` and `ExtendedPoint#toRawBytes()`
-5. Have `assertValidity()` which checks for being on-curve
-6. Have `toAffine()` and `x` / `y` getters which convert to 2d xy affine coordinates
-7. Have `isTorsionFree()`, `clearCofactor()` and `isSmallOrder()` utilities to handle torsions
-
-```ts
-interface ExtPointType extends Group<ExtPointType> {
-  readonly ex: bigint;
-  readonly ey: bigint;
-  readonly ez: bigint;
-  readonly et: bigint;
-  assertValidity(): void;
-  multiply(scalar: bigint): ExtPointType;
-  multiplyUnsafe(scalar: bigint): ExtPointType;
-  isSmallOrder(): boolean;
-  isTorsionFree(): boolean;
-  clearCofactor(): ExtPointType;
-  toAffine(iz?: bigint): AffinePoint<bigint>;
-}
-// Static methods of Extended Point with coordinates in X, Y, Z, T
-interface ExtPointConstructor extends GroupConstructor<ExtPointType> {
-  new (x: bigint, y: bigint, z: bigint, t: bigint): ExtPointType;
-  fromAffine(p: AffinePoint<bigint>): ExtPointType;
-  fromHex(hex: Hex): ExtPointType;
-  fromPrivateKey(privateKey: Hex): ExtPointType;
-}
-```
-
-Example implementing edwards25519:
-
 ```ts
 import { twistedEdwards } from '@noble/curves/abstract/edwards';
-import { Field, div } from '@noble/curves/abstract/modular';
+import { Field } from '@noble/curves/abstract/modular';
 import { sha512 } from '@noble/hashes/sha512';
+import { randomBytes } from '@noble/hashes/utils';
 
 const Fp = Field(2n ** 255n - 19n);
 const ed25519 = twistedEdwards({
   a: -1n,
   d: Fp.div(-121665n, 121666n), // -121665n/121666n mod p
-  Fp,
+  Fp: Fp,
   n: 2n ** 252n + 27742317777372353535851937790883648493n,
   h: 8n,
   Gx: 15112221349535400772501151409588531511454012693041857206046113283949847762202n,
@@ -420,9 +407,23 @@ const ed25519 = twistedEdwards({
 } as const);
 ```
 
-`twistedEdwards()` returns `CurveFn` of following type:
+Twisted Edwards curve's formula is `ax² + y² = 1 + dx²y²`. You must specify `a`, `d`, field `Fp`, order `n`, cofactor `h`
+and coordinates `Gx`, `Gy` of generator point.
+
+For EdDSA signatures, `hash` param required. `adjustScalarBytes` which instructs how to change private scalars could be specified.
+
+**Edwards points:**
+
+1. Exported as `ExtendedPoint`
+2. Represented in extended coordinates: (x, y, z, t) ∋ (x=x/z, y=y/z)
+3. Use complete exception-free formulas for addition and doubling
+4. Can be decoded/encoded from/to Uint8Array / hex strings using `ExtendedPoint.fromHex` and `ExtendedPoint#toRawBytes()`
+5. Have `assertValidity()` which checks for being on-curve
+6. Have `toAffine()` and `x` / `y` getters which convert to 2d xy affine coordinates
+7. Have `isTorsionFree()`, `clearCofactor()` and `isSmallOrder()` utilities to handle torsions
 
 ```ts
+// `twistedEdwards()` returns `CurveFn` of following type:
 type CurveFn = {
   CURVE: ReturnType<typeof validateOpts>;
   getPublicKey: (privateKey: Hex) => Uint8Array;
@@ -440,21 +441,39 @@ type CurveFn = {
     };
   };
 };
+
+interface ExtPointType extends Group<ExtPointType> {
+  readonly ex: bigint;
+  readonly ey: bigint;
+  readonly ez: bigint;
+  readonly et: bigint;
+  assertValidity(): void;
+  multiply(scalar: bigint): ExtPointType;
+  multiplyUnsafe(scalar: bigint): ExtPointType;
+  isSmallOrder(): boolean;
+  isTorsionFree(): boolean;
+  clearCofactor(): ExtPointType;
+  toAffine(iz?: bigint): AffinePoint<bigint>;
+}
+// Static methods of Extended Point with coordinates in X, Y, Z, T
+interface ExtPointConstructor extends GroupConstructor<ExtPointType> {
+  new (x: bigint, y: bigint, z: bigint, t: bigint): ExtPointType;
+  fromAffine(p: AffinePoint<bigint>): ExtPointType;
+  fromHex(hex: Hex): ExtPointType;
+  fromPrivateKey(privateKey: Hex): ExtPointType;
+}
 ```
 
 ### abstract/montgomery: Montgomery curve
 
-The module contains methods for x-only ECDH on Curve25519 / Curve448 from RFC7748. Proper Elliptic Curve Points are not implemented yet.
-
-You must specify curve params `Fp`, `a`, `Gu` coordinate of u, `montgomeryBits` and `nByteLength`.
-
 ```typescript
 import { montgomery } from '@noble/curves/abstract/montgomery';
+import { Field } from '@noble/curves/abstract/modular';
 
 const x25519 = montgomery({
-  Fp: Field(2n ** 255n - 19n),
   a: 486662n,
   Gu: 9n,
+  Fp: Field(2n ** 255n - 19n),
   montgomeryBits: 255,
   nByteLength: 32,
   // Optional param
@@ -467,6 +486,11 @@ const x25519 = montgomery({
 });
 ```
 
+The module contains methods for x-only ECDH on Curve25519 / Curve448 from RFC7748.
+Proper Elliptic Curve Points are not implemented yet.
+
+You must specify curve params `Fp`, `a`, `Gu` coordinate of u, `montgomeryBits` and `nByteLength`.
+
 ### abstract/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).
@@ -507,19 +531,37 @@ function expand_message_xof(
 ): Uint8Array;
 ```
 
-`hash_to_field(msg, count, options)` [(spec)](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hash-to-curve-11#section-5.3)
+`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.
 
-- `msg` a byte string containing the message to hash
-- `count` the number of elements of F to output
-- `options` `{DST: string, p: bigint, m: number, k: number, expand: 'xmd' | 'xof', hash: H}`.
-  - `p` is field prime, m=field extension (1 for prime fields)
-  - `k` is security target in bits (e.g. 128).
-  - `expand` should be `xmd` for SHA2, SHA3, BLAKE; `xof` for SHAKE, BLAKE-XOF
-  - `hash` conforming to `utils.CHash` interface, with `outputLen` / `blockLen` props
-- Returns `[u_0, ..., u_(count - 1)]`, a list of field elements.
-
 ```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
+ * * `m` is extension degree (1 for prime fields)
+ * * `k` is the target security target in bits (e.g. 128), from section 5.1
+ * * `expand` is `xmd` (SHA2, SHA3, BLAKE) or `xof` (SHAKE, BLAKE-XOF)
+ * * `hash` conforming to `utils.CHash` interface, with `outputLen` / `blockLen` props
+ */
+type UnicodeOrBytes = string | Uint8Array;
+type Opts = {
+    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[][];
 ```
 
@@ -704,6 +746,13 @@ hashToCurve
 └─ed448 x 1,045 ops/sec @ 956μ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
+
 ## Resources
 
 Article about some of library's features: [Learning fast elliptic-curve cryptography](https://paulmillr.com/posts/noble-secp256k1-fast-ecc/)
@@ -719,45 +768,52 @@ Projects using the library:
   - Threshold sigs demo [genthresh.com](https://genthresh.com)
   - BBS signatures [github.com/Wind4Greg/BBS-Draft-Checks](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)
 - Others
-  - All curves demo: Elliptic curve calculator [paulmillr.com/ecc](https://paulmillr.com/ecc)
+  - All curves demo: Elliptic curve calculator [paulmillr.com/noble](https://paulmillr.com/noble)
   - [micro-starknet](https://github.com/paulmillr/micro-starknet) for stark-friendly elliptic curve.
+
 ## Upgrading
 
-If you're coming from single-feature noble packages, the following changes need to be kept in mind:
-
-- 2d affine (x, y) points have been removed to reduce complexity and improve speed
-- Removed `number` support as a type for private keys, `bigint` is still supported
-- `mod`, `invert` are no longer present in `utils`: use `@noble/curves/abstract/modular`
-
-Upgrading from @noble/secp256k1 1.7:
-
-- Compressed (33-byte) public keys are now returned by default, instead of uncompressed
-- Methods are now synchronous. Setting `secp.utils.hmacSha256` is no longer required
-- `sign()`
-  - `der`, `recovered` options were removed
-  - `canonical` was renamed to `lowS`
-  - Return type is now `{ r: bigint, s: bigint, recovery: number }` instance of `Signature`
-- `verify()`
-  - `strict` was renamed to `lowS`
-- `recoverPublicKey()`: moved to sig instance `Signature#recoverPublicKey(msgHash)`
-- `Point` was removed: use `ProjectivePoint` in xyz coordinates
-- `utils`: Many methods were removed, others were moved to `schnorr` namespace
-
-Upgrading from @noble/ed25519 1.7:
-
-- Methods are now synchronous. Setting `secp.utils.hmacSha256` is no longer required
-- ed25519ph, ed25519ctx
-- `Point` was removed: use `ExtendedPoint` in xyzt coordinates
-- `Signature` was removed
-- `getSharedSecret` was removed: use separate x25519 sub-module
+Previously, the library was split into single-feature packages
+noble-secp256k1 and noble-ed25519. curves can be thought as a continuation of their
+original work. The libraries now changed their direction towards providing
+minimal 4kb implementations of cryptography and are not as feature-complete.
+
+Upgrading from [@noble/secp256k1](https://github.com/paulmillr/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)`
+- `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).
+- `verify`
+    - `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)`
+- `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)
+- `utils` were split into `utils` (same api as in noble-curves) and
+  `etc` (`hmacSha256Sync` and others)
+
+Upgrading from [@noble/ed25519](https://github.com/paulmillr/noble-ed25519) 1.7:
+
+- Methods are now sync by default
 - `bigint` is no longer allowed in `getPublicKey`, `sign`, `verify`. Reason: ed25519 is LE, can lead to bugs
-
-## 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
+- `Point` (2d xy) has been changed to `ExtendedPoint` (xyzt)
+- `Signature` was removed: just use raw bytes or hex now
+- `utils` were split into `utils` (same api as in noble-curves) and
+  `etc` (`sha512Sync` and others)
+- `getSharedSecret` was moved to `x25519` module
 
 ## License
 

package/_shortw_utils.d.ts

@@ -6,13 +6,13 @@ export declare function getHash(hash: CHash): {
     hmac: (key: Uint8Array, ...msgs: Uint8Array[]) => Uint8Array;
     randomBytes: typeof randomBytes;
 };
-declare type CurveDef = Readonly<Omit<CurveType, 'hash' | 'hmac' | 'randomBytes'>>;
+type CurveDef = Readonly<Omit<CurveType, 'hash' | 'hmac' | 'randomBytes'>>;
 export declare function createCurve(curveDef: CurveDef, defHash: CHash): Readonly<{
     create: (hash: CHash) => import("./abstract/weierstrass.js").CurveFn;
     CURVE: Readonly<{
         readonly nBitLength: number;
         readonly nByteLength: number;
-        readonly Fp: import("./abstract/modular.js").Field<bigint>;
+        readonly Fp: import("./abstract/modular.js").IField<bigint>;
         readonly n: bigint;
         readonly h: bigint;
         readonly hEff?: bigint | undefined;
@@ -40,6 +40,7 @@ export declare function createCurve(curveDef: CurveDef, defHash: CHash): Readonl
         lowS: boolean;
         readonly bits2int?: ((bytes: Uint8Array) => bigint) | undefined;
         readonly bits2int_modN?: ((bytes: Uint8Array) => bigint) | undefined;
+        readonly p: bigint;
     }>;
     getPublicKey: (privateKey: import("./abstract/utils.js").PrivKey, isCompressed?: boolean | undefined) => Uint8Array;
     getSharedSecret: (privateA: import("./abstract/utils.js").PrivKey, publicB: import("./abstract/utils.js").Hex, isCompressed?: boolean | undefined) => Uint8Array;

package/_shortw_utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_shortw_utils.d.ts","sourceRoot":"","sources":["src/_shortw_utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAe,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAe,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAG5C,wBAAgB,OAAO,CAAC,IAAI,EAAE,KAAK;;gBAGnB,UAAU,WAAW,UAAU,EAAE;;EAGhD;AAED,aAAK,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC;AAC3E,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK;mBACtC,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAE5B"}
+{"version":3,"file":"_shortw_utils.d.ts","sourceRoot":"","sources":["src/_shortw_utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAe,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAe,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAG5C,wBAAgB,OAAO,CAAC,IAAI,EAAE,KAAK;;gBAGnB,UAAU,WAAW,UAAU,EAAE;;EAGhD;AAED,KAAK,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC;AAC3E,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK;mBACtC,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAE5B"}