@noble/curves 0.5.1 → 0.6.0

package/README.md

@@ -6,7 +6,9 @@ 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
+- Auditable
+- 🏎 [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
 
@@ -24,7 +26,6 @@ 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.
 
 ### 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)
 
@@ -201,8 +203,6 @@ export type CurveFn = {
   ExtendedPoint: ExtendedPointConstructor;
   Signature: SignatureConstructor;
   utils: {
-    mod: (a: bigint, b?: bigint) => bigint;
-    invert: (number: bigint, modulo?: bigint) => bigint;
     randomPrivateKey: () => Uint8Array;
     getExtendedPublicKey: (key: PrivKey) => {
       head: Uint8Array;
@@ -304,20 +304,18 @@ 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;
   verify: (
     signature: Hex | SignatureType,
     msgHash: Hex,
-    publicKey: PubKey,
+    publicKey: Hex,
     opts?: { lowS?: boolean }
   ) => boolean;
   Point: PointConstructor;
   ProjectivePoint: ProjectivePointConstructor;
   Signature: SignatureConstructor;
   utils: {
-    mod: (a: bigint) => bigint;
-    invert: (number: bigint) => bigint;
     isValidPrivateKey(privateKey: PrivKey): boolean;
     hashToPrivateKey: (hash: Hex) => Uint8Array;
     randomPrivateKey: () => Uint8Array;
@@ -373,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.
@@ -462,6 +484,25 @@ verify
   noble x 698 ops/sec @ 1ms/op
 ```
 
+## Upgrading
+
+Differences from @noble/secp256k1 1.7:
+
+1. Different double() formula (but same addition)
+2. Different sqrt() function
+3. DRBG supports outputLen bigger than outputLen of hmac
+4. Support for different hash functions
+
+Differences from @noble/ed25519 1.7:
+
+1. Variable field element lengths between EDDSA/ECDH:
+  EDDSA (RFC8032) is 456 bits / 57 bytes, ECDH (RFC7748) is 448 bits / 56 bytes
+2. Different addition formula (doubling is same)
+3. uvRatio differs between curves (half-expected, not only pow fn changes)
+4. Point decompression code is different (unexpected), now using generalized formula
+5. Domain function was no-op for ed25519, but adds some data even with empty context for ed448
+
+
 ## Contributing & testing
 
 1. Clone the repository

package/lib/_shortw_utils.d.ts

@@ -32,41 +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;
+        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;
         lowS: boolean;
         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;
+        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;
-    sign: (msgHash: import("./abstract/utils.js").Hex, privKey: import("./abstract/utils.js").PrivKey, opts?: {
-        lowS?: boolean | undefined;
-        extraEntropy?: (true | import("./abstract/utils.js").Hex) | undefined;
-    } | 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>;
+    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;
+    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: {
-        mod: (a: bigint, b?: bigint | undefined) => bigint;
-        invert: (number: bigint, modulo?: bigint | undefined) => bigint;
-        _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

@@ -1,24 +1,41 @@
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
-import * as mod from './modular.js';
-import * as utils from './utils.js';
-import { Hex, PrivKey } from './utils.js';
-import { htfOpts, stringToBytes, hash_to_field, expand_message_xmd } from './hash-to-curve.js';
-import { CurvePointsType, PointType, CurvePointsRes } from './weierstrass.js';
+/**
+ * BLS (Barreto-Lynn-Scott) family of pairing-friendly curves.
+ * Implements BLS (Boneh-Lynn-Shacham) signatures.
+ * Consists of two curves: G1 and G2:
+ * - G1 is a subgroup of (x, y) E(Fq) over y² = x³ + 4.
+ * - G2 is a subgroup of ((x₁, x₂+i), (y₁, y₂+i)) E(Fq²) over y² = x³ + 4(1 + i) where i is √-1
+ * - Gt, created by bilinear (ate) pairing e(G1, G2), consists of p-th roots of unity in
+ *   Fq^k where k is embedding degree. Only degree 12 is currently supported, 24 is not.
+ * Pairing is used to aggregate and verify signatures.
+ * 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 { 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;
@@ -26,54 +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: utils.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: {
-        bytesToHex: typeof utils.bytesToHex;
-        hexToBytes: typeof utils.hexToBytes;
-        stringToBytes: typeof stringToBytes;
-        hashToField: typeof hash_to_field;
-        expandMessageXMD: typeof expand_message_xmd;
-        mod: typeof mod.mod;
-        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>;