@noble/curves 0.5.2 → 0.6.1

package/README.md

@@ -6,11 +6,12 @@ Minimal, auditable JS implementation of elliptic curve cryptography.
 - ECDSA, EdDSA, Schnorr, BLS signature schemes, ECDH key agreement
 - [hash to curve](https://datatracker.ietf.org/doc/draft-irtf-cfrg-hash-to-curve/)
   for encoding or hashing an arbitrary string to a point on an elliptic curve
-- Auditable, [fast](#speed)
+- [Poseidon](https://www.poseidon-hash.info) ZK-friendly hash
+- 🏎 [Ultra-fast](#speed), hand-optimized for caveats of JS engines
 - 🔍 Unique tests ensure correctness. Wycheproof vectors included
 - 🔻 Tree-shaking-friendly: there is no entry point, which ensures small size of your app
 
-There are two parts of the package:
+Package consists of two parts:
 
 1. `abstract/` directory specifies zero-dependency EC algorithms
 2. root directory utilizes one dependency `@noble/hashes` and provides ready-to-use:
@@ -24,7 +25,7 @@ Curves incorporate work from previous noble packages
 [ed25519](https://github.com/paulmillr/noble-ed25519),
 [bls12-381](https://github.com/paulmillr/noble-bls12-381)),
 which had security audits and were developed from 2019 to 2022.
-The goal is to replace them with lean UMD builds based on single-codebase noble-curves.
+Check out [Upgrading](#upgrading) section if you've used them before.
 
 ### This library belongs to _noble_ crypto
 
@@ -88,6 +89,7 @@ To define a custom curve, check out API below.
 - [abstract/montgomery: Montgomery curve](#abstractmontgomery-montgomery-curve)
 - [abstract/weierstrass: Short Weierstrass curve](#abstractweierstrass-short-weierstrass-curve)
 - [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](#abstractmodular)
 - [abstract/utils](#abstractutils)
 
@@ -302,13 +304,12 @@ const shared = secp256k1.getSharedSecret(key, someonesPubkey);
 export type CurveFn = {
   CURVE: ReturnType<typeof validateOpts>;
   getPublicKey: (privateKey: PrivKey, isCompressed?: boolean) => Uint8Array;
-  getSharedSecret: (privateA: PrivKey, publicB: PubKey, isCompressed?: boolean) => Uint8Array;
+  getSharedSecret: (privateA: PrivKey, publicB: Hex, isCompressed?: boolean) => Uint8Array;
   sign: (msgHash: Hex, privKey: PrivKey, opts?: SignOpts) => SignatureType;
-  signUnhashed: (msg: Uint8Array, privKey: PrivKey, opts?: SignOpts) => SignatureType;
   verify: (
     signature: Hex | SignatureType,
     msgHash: Hex,
-    publicKey: PubKey,
+    publicKey: Hex,
     opts?: { lowS?: boolean }
   ) => boolean;
   Point: PointConstructor;
@@ -370,6 +371,30 @@ hashes arbitrary-length byte strings to a list of one or more elements of a fini
     };
     ```
 
+### abstract/poseidon: Poseidon hash
+
+Implements [Poseidon](https://www.poseidon-hash.info) ZK-friendly hash.
+
+There are many poseidon instances with different constants. We don't provide them,
+but we provide ability to specify them manually. For actual usage, check out
+stark curve source code.
+
+```ts
+import { poseidon } from '@noble/curves/abstract/poseidon';
+
+type PoseidonOpts = {
+  Fp: Field<bigint>;
+  t: number;
+  roundsFull: number;
+  roundsPartial: number;
+  sboxPower?: number;
+  reversePartialPowIdx?: boolean; // Hack for stark
+  mds: bigint[][];
+  roundConstants: bigint[][];
+};
+const instance = poseidon(opts: PoseidonOpts);
+```
+
 ### abstract/modular
 
 Modular arithmetics utilities.
@@ -420,45 +445,94 @@ We consider infrastructure attacks like rogue NPM modules very important; that's
 Benchmark results on Apple M2 with node v18.10:
 
 ```
-getPublicKey
-  secp256k1 x 5,241 ops/sec @ 190μs/op
-  P256 x 7,993 ops/sec @ 125μs/op
-  P384 x 3,819 ops/sec @ 261μs/op
-  P521 x 2,074 ops/sec @ 481μs/op
-  ed25519 x 8,390 ops/sec @ 119μs/op
-  ed448 x 3,224 ops/sec @ 310μs/op
-sign
-  secp256k1 x 3,934 ops/sec @ 254μs/op
-  P256 x 5,327 ops/sec @ 187μs/op
-  P384 x 2,728 ops/sec @ 366μs/op
-  P521 x 1,594 ops/sec @ 626μs/op
-  ed25519 x 4,233 ops/sec @ 236μs/op
-  ed448 x 1,561 ops/sec @ 640μs/op
-verify
-  secp256k1 x 731 ops/sec @ 1ms/op
-  P256 x 806 ops/sec @ 1ms/op
-  P384 x 353 ops/sec @ 2ms/op
-  P521 x 171 ops/sec @ 5ms/op
-  ed25519 x 860 ops/sec @ 1ms/op
-  ed448 x 313 ops/sec @ 3ms/op
-getSharedSecret
-  secp256k1 x 445 ops/sec @ 2ms/op
-recoverPublicKey
-  secp256k1 x 732 ops/sec @ 1ms/op
-==== bls12-381 ====
-getPublicKey x 817 ops/sec @ 1ms/op
-sign x 50 ops/sec @ 19ms/op
-verify x 34 ops/sec @ 28ms/op
-pairing x 89 ops/sec @ 11ms/op
-==== stark ====
+secp256k1
+init x 57 ops/sec @ 17ms/op
+getPublicKey x 4,946 ops/sec @ 202μs/op
+sign x 3,914 ops/sec @ 255μs/op
+verify x 682 ops/sec @ 1ms/op
+getSharedSecret x 427 ops/sec @ 2ms/op
+recoverPublicKey x 683 ops/sec @ 1ms/op
+schnorr.sign x 539 ops/sec @ 1ms/op
+schnorr.verify x 716 ops/sec @ 1ms/op
+
+P256
+init x 30 ops/sec @ 32ms/op
+getPublicKey x 5,008 ops/sec @ 199μs/op
+sign x 3,970 ops/sec @ 251μs/op
+verify x 515 ops/sec @ 1ms/op
+
+P384
+init x 14 ops/sec @ 66ms/op
+getPublicKey x 2,434 ops/sec @ 410μs/op
+sign x 1,942 ops/sec @ 514μs/op
+verify x 206 ops/sec @ 4ms/op
+
+P521
+init x 7 ops/sec @ 126ms/op
+getPublicKey x 1,282 ops/sec @ 779μs/op
+sign x 1,077 ops/sec @ 928μs/op
+verify x 110 ops/sec @ 9ms/op
+
+ed25519
+init x 37 ops/sec @ 26ms/op
+getPublicKey x 8,147 ops/sec @ 122μs/op
+sign x 3,979 ops/sec @ 251μs/op
+verify x 848 ops/sec @ 1ms/op
+
+ed448
+init x 17 ops/sec @ 58ms/op
+getPublicKey x 3,083 ops/sec @ 324μs/op
+sign x 1,473 ops/sec @ 678μs/op
+verify x 323 ops/sec @ 3ms/op
+
+bls12-381
+init x 30 ops/sec @ 33ms/op
+getPublicKey x 788 ops/sec @ 1ms/op
+sign x 45 ops/sec @ 21ms/op
+verify x 32 ops/sec @ 30ms/op
+pairing x 88 ops/sec @ 11ms/op
+
+stark
+init x 31 ops/sec @ 31ms/op
 pedersen
-  old x 85 ops/sec @ 11ms/op
-  noble x 1,216 ops/sec @ 822μs/op
+├─old x 84 ops/sec @ 11ms/op
+└─noble x 802 ops/sec @ 1ms/op
+poseidon x 7,466 ops/sec @ 133μs/op
 verify
-  old x 302 ops/sec @ 3ms/op
-  noble x 698 ops/sec @ 1ms/op
+├─old x 300 ops/sec @ 3ms/op
+└─noble x 474 ops/sec @ 2ms/op
 ```
 
+## Upgrading
+
+If you're coming from single-curve 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.js` now.
+
+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
+
 ## Contributing & testing
 
 1. Clone the repository

package/lib/_shortw_utils.d.ts

@@ -18,11 +18,11 @@ export declare function createCurve(curveDef: CurveDef, defHash: CHash): Readonl
         readonly hEff?: bigint | undefined;
         readonly Gx: bigint;
         readonly Gy: bigint;
-        readonly wrapPrivateKey?: boolean | undefined;
         readonly allowInfinityPoint?: boolean | undefined;
         readonly a: bigint;
         readonly b: bigint;
-        readonly normalizePrivateKey?: ((key: import("./abstract/utils.js").PrivKey) => import("./abstract/utils.js").PrivKey) | undefined;
+        readonly allowedPrivateKeyLengths?: readonly number[] | undefined;
+        readonly wrapPrivateKey?: boolean | undefined;
         readonly endo?: {
             beta: bigint;
             splitScalar: (k: bigint) => {
@@ -32,37 +32,26 @@ export declare function createCurve(curveDef: CurveDef, defHash: CHash): Readonl
                 k2: bigint;
             };
         } | undefined;
-        readonly isTorsionFree?: ((c: import("./abstract/weierstrass.js").ProjectiveConstructor<bigint>, point: import("./abstract/weierstrass.js").ProjectivePointType<bigint>) => boolean) | undefined;
-        readonly clearCofactor?: ((c: import("./abstract/weierstrass.js").ProjectiveConstructor<bigint>, point: import("./abstract/weierstrass.js").ProjectivePointType<bigint>) => import("./abstract/weierstrass.js").ProjectivePointType<bigint>) | undefined;
-        readonly htfDefaults?: import("./abstract/hash-to-curve.js").htfOpts | undefined;
-        readonly mapToCurve?: ((scalar: bigint[]) => {
-            x: bigint;
-            y: bigint;
-        }) | undefined;
-        lowS: boolean;
+        readonly isTorsionFree?: ((c: import("./abstract/weierstrass.js").ProjConstructor<bigint>, point: import("./abstract/weierstrass.js").ProjPointType<bigint>) => boolean) | undefined;
+        readonly clearCofactor?: ((c: import("./abstract/weierstrass.js").ProjConstructor<bigint>, point: import("./abstract/weierstrass.js").ProjPointType<bigint>) => import("./abstract/weierstrass.js").ProjPointType<bigint>) | undefined;
         readonly hash: CHash;
         readonly hmac: (key: Uint8Array, ...messages: Uint8Array[]) => Uint8Array;
         readonly randomBytes: (bytesLength?: number | undefined) => Uint8Array;
-        readonly truncateHash?: ((hash: Uint8Array, truncateOnly?: boolean | undefined) => bigint) | undefined;
+        lowS: boolean;
+        readonly bits2int?: ((bytes: Uint8Array) => bigint) | undefined;
+        readonly bits2int_modN?: ((bytes: Uint8Array) => bigint) | undefined;
     }>;
     getPublicKey: (privateKey: import("./abstract/utils.js").PrivKey, isCompressed?: boolean | undefined) => Uint8Array;
-    getSharedSecret: (privateA: import("./abstract/utils.js").PrivKey, publicB: import("./abstract/weierstrass.js").PubKey, isCompressed?: boolean | undefined) => Uint8Array;
+    getSharedSecret: (privateA: import("./abstract/utils.js").PrivKey, publicB: import("./abstract/utils.js").Hex, isCompressed?: boolean | undefined) => Uint8Array;
     sign: (msgHash: import("./abstract/utils.js").Hex, privKey: import("./abstract/utils.js").PrivKey, opts?: import("./abstract/weierstrass.js").SignOpts | undefined) => import("./abstract/weierstrass.js").SignatureType;
-    signUnhashed: (msg: Uint8Array, privKey: import("./abstract/utils.js").PrivKey, opts?: import("./abstract/weierstrass.js").SignOpts | undefined) => import("./abstract/weierstrass.js").SignatureType;
-    verify: (signature: import("./abstract/utils.js").Hex | import("./abstract/weierstrass.js").SignatureType, msgHash: import("./abstract/utils.js").Hex, publicKey: import("./abstract/weierstrass.js").PubKey, opts?: {
-        lowS?: boolean | undefined;
-    } | undefined) => boolean;
-    Point: import("./abstract/weierstrass.js").PointConstructor<bigint>;
-    ProjectivePoint: import("./abstract/weierstrass.js").ProjectiveConstructor<bigint>;
+    verify: (signature: import("./abstract/utils.js").Hex | {
+        r: bigint;
+        s: bigint;
+    }, msgHash: import("./abstract/utils.js").Hex, publicKey: import("./abstract/utils.js").Hex, opts?: import("./abstract/weierstrass.js").VerOpts | undefined) => boolean;
+    ProjectivePoint: import("./abstract/weierstrass.js").ProjConstructor<bigint>;
     Signature: import("./abstract/weierstrass.js").SignatureConstructor;
     utils: {
-        _bigintToBytes: (num: bigint) => Uint8Array;
-        _bigintToString: (num: bigint) => string;
         _normalizePrivateKey: (key: import("./abstract/utils.js").PrivKey) => bigint;
-        _normalizePublicKey: (publicKey: import("./abstract/weierstrass.js").PubKey) => import("./abstract/weierstrass.js").PointType<bigint>;
-        _isWithinCurveOrder: (num: bigint) => boolean;
-        _isValidFieldElement: (num: bigint) => boolean;
-        _weierstrassEquation: (x: bigint) => bigint;
         isValidPrivateKey(privateKey: import("./abstract/utils.js").PrivKey): boolean;
         hashToPrivateKey: (hash: import("./abstract/utils.js").Hex) => Uint8Array;
         randomPrivateKey: () => Uint8Array;

package/lib/abstract/bls.d.ts

@@ -11,26 +11,31 @@
  * We are using Fp for private keys (shorter) and Fp₂ for signatures (longer).
  * Some projects may prefer to swap this relation, it is not supported for now.
  */
-import * as mod from './modular.js';
-import * as ut from './utils.js';
-import { Hex, PrivKey } from './utils.js';
-import { htfOpts, stringToBytes, hash_to_field as hashToField, expand_message_xmd as expandMessageXMD } from './hash-to-curve.js';
-import { CurvePointsType, PointType, CurvePointsRes } from './weierstrass.js';
+import { AffinePoint } from './curve.js';
+import { Field } from './modular.js';
+import { Hex, PrivKey, CHash } from './utils.js';
+import * as htf from './hash-to-curve.js';
+import { CurvePointsType, ProjPointType as ProjPointType, CurvePointsRes } from './weierstrass.js';
 declare type Fp = bigint;
 export declare type SignatureCoder<Fp2> = {
-    decode(hex: Hex): PointType<Fp2>;
-    encode(point: PointType<Fp2>): Uint8Array;
+    decode(hex: Hex): ProjPointType<Fp2>;
+    encode(point: ProjPointType<Fp2>): Uint8Array;
 };
 export declare type CurveType<Fp, Fp2, Fp6, Fp12> = {
     r: bigint;
-    G1: Omit<CurvePointsType<Fp>, 'n'>;
+    G1: Omit<CurvePointsType<Fp>, 'n'> & {
+        mapToCurve: htf.MapToCurve<Fp>;
+        htfDefaults: htf.Opts;
+    };
     G2: Omit<CurvePointsType<Fp2>, 'n'> & {
         Signature: SignatureCoder<Fp2>;
+        mapToCurve: htf.MapToCurve<Fp2>;
+        htfDefaults: htf.Opts;
     };
     x: bigint;
-    Fp: mod.Field<Fp>;
-    Fr: mod.Field<bigint>;
-    Fp2: mod.Field<Fp2> & {
+    Fp: Field<Fp>;
+    Fr: Field<bigint>;
+    Fp2: Field<Fp2> & {
         reim: (num: Fp2) => {
             re: bigint;
             im: bigint;
@@ -38,51 +43,53 @@ export declare type CurveType<Fp, Fp2, Fp6, Fp12> = {
         multiplyByB: (num: Fp2) => Fp2;
         frobeniusMap(num: Fp2, power: number): Fp2;
     };
-    Fp6: mod.Field<Fp6>;
-    Fp12: mod.Field<Fp12> & {
+    Fp6: Field<Fp6>;
+    Fp12: Field<Fp12> & {
         frobeniusMap(num: Fp12, power: number): Fp12;
         multiplyBy014(num: Fp12, o0: Fp2, o1: Fp2, o4: Fp2): Fp12;
         conjugate(num: Fp12): Fp12;
         finalExponentiate(num: Fp12): Fp12;
     };
-    htfDefaults: htfOpts;
-    hash: ut.CHash;
+    htfDefaults: htf.Opts;
+    hash: CHash;
     randomBytes: (bytesLength?: number) => Uint8Array;
 };
 export declare type CurveFn<Fp, Fp2, Fp6, Fp12> = {
     CURVE: CurveType<Fp, Fp2, Fp6, Fp12>;
-    Fr: mod.Field<bigint>;
-    Fp: mod.Field<Fp>;
-    Fp2: mod.Field<Fp2>;
-    Fp6: mod.Field<Fp6>;
-    Fp12: mod.Field<Fp12>;
+    Fr: Field<bigint>;
+    Fp: Field<Fp>;
+    Fp2: Field<Fp2>;
+    Fp6: Field<Fp6>;
+    Fp12: Field<Fp12>;
     G1: CurvePointsRes<Fp>;
     G2: CurvePointsRes<Fp2>;
     Signature: SignatureCoder<Fp2>;
     millerLoop: (ell: [Fp2, Fp2, Fp2][], g1: [Fp, Fp]) => Fp12;
-    calcPairingPrecomputes: (x: Fp2, y: Fp2) => [Fp2, Fp2, Fp2][];
-    pairing: (P: PointType<Fp>, Q: PointType<Fp2>, withFinalExponent?: boolean) => Fp12;
+    calcPairingPrecomputes: (p: AffinePoint<Fp2>) => [Fp2, Fp2, Fp2][];
+    hashToCurve: {
+        G1: ReturnType<(typeof htf.hashToCurve<Fp>)>;
+        G2: ReturnType<(typeof htf.hashToCurve<Fp2>)>;
+    };
+    pairing: (P: ProjPointType<Fp>, Q: ProjPointType<Fp2>, withFinalExponent?: boolean) => Fp12;
     getPublicKey: (privateKey: PrivKey) => Uint8Array;
     sign: {
         (message: Hex, privateKey: PrivKey): Uint8Array;
-        (message: PointType<Fp2>, privateKey: PrivKey): PointType<Fp2>;
+        (message: ProjPointType<Fp2>, privateKey: PrivKey): ProjPointType<Fp2>;
     };
-    verify: (signature: Hex | PointType<Fp2>, message: Hex | PointType<Fp2>, publicKey: Hex | PointType<Fp>) => boolean;
+    verify: (signature: Hex | ProjPointType<Fp2>, message: Hex | ProjPointType<Fp2>, publicKey: Hex | ProjPointType<Fp>) => boolean;
     aggregatePublicKeys: {
         (publicKeys: Hex[]): Uint8Array;
-        (publicKeys: PointType<Fp>[]): PointType<Fp>;
+        (publicKeys: ProjPointType<Fp>[]): ProjPointType<Fp>;
     };
     aggregateSignatures: {
         (signatures: Hex[]): Uint8Array;
-        (signatures: PointType<Fp2>[]): PointType<Fp2>;
+        (signatures: ProjPointType<Fp2>[]): ProjPointType<Fp2>;
     };
-    verifyBatch: (signature: Hex | PointType<Fp2>, messages: (Hex | PointType<Fp2>)[], publicKeys: (Hex | PointType<Fp>)[]) => boolean;
+    verifyBatch: (signature: Hex | ProjPointType<Fp2>, messages: (Hex | ProjPointType<Fp2>)[], publicKeys: (Hex | ProjPointType<Fp>)[]) => boolean;
     utils: {
-        stringToBytes: typeof stringToBytes;
-        hashToField: typeof hashToField;
-        expandMessageXMD: typeof expandMessageXMD;
-        getDSTLabel: () => string;
-        setDSTLabel(newLabel: string): void;
+        stringToBytes: typeof htf.stringToBytes;
+        hashToField: typeof htf.hash_to_field;
+        expandMessageXMD: typeof htf.expand_message_xmd;
     };
 };
 export declare function bls<Fp2, Fp6, Fp12>(CURVE: CurveType<Fp, Fp2, Fp6, Fp12>): CurveFn<Fp, Fp2, Fp6, Fp12>;