0
# @noble/curves
1

2
@noble/curves is a comprehensive, audited JavaScript/TypeScript implementation of elliptic curve cryptography. It provides multiple curve implementations (secp256k1, ed25519, NIST curves, BLS curves) with ECDSA, EdDSA, and Schnorr signature schemes, hash-to-curve functionality, and modular abstract cryptographic primitives for building custom curve implementations.
3

4
## Package Information
5

6
- **Package Name**: @noble/curves
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @noble/curves`
10

11
## Core Imports
12

13
**Important**: The main index cannot be imported directly - you must import specific submodules:
14

15
```typescript
16
// Curve implementations
17
import { secp256k1, schnorr } from "@noble/curves/secp256k1";
18
import { ed25519, ed25519ph, ed25519ctx, x25519, RistrettoPoint } from "@noble/curves/ed25519";
19
import { p256, p384, p521 } from "@noble/curves/nist";
20
import { bls12_381 } from "@noble/curves/bls12-381";
21
import { bn254 } from "@noble/curves/bn254";
22

23
// Abstract primitives
24
import { Field, mod, pow, invert } from "@noble/curves/abstract/modular";
25
import { weierstrass, ecdsa, ecdh } from "@noble/curves/abstract/weierstrass";
26
import { twistedEdwards, eddsa } from "@noble/curves/abstract/edwards";
27

28
// Utilities
29
import { bytesToHex, hexToBytes, concatBytes, randomBytes } from "@noble/curves/utils";
30
```
31

32
For CommonJS:
33

34
```javascript
35
const { secp256k1, schnorr } = require("@noble/curves/secp256k1");
36
const { ed25519, x25519 } = require("@noble/curves/ed25519");
37
const { p256, p384, p521 } = require("@noble/curves/nist");
38
```
39

40
## Basic Usage
41

42
```typescript
43
import { secp256k1 } from "@noble/curves/secp256k1";
44
import { ed25519 } from "@noble/curves/ed25519";
45
import { randomBytes } from "@noble/curves/utils";
46

47
// ECDSA with secp256k1
48
const privKey = randomBytes(32);
49
const pubKey = secp256k1.getPublicKey(privKey);
50
const message = new TextEncoder().encode("hello world");
51

52
const signature = secp256k1.sign(message, privKey);
53
const isValid = secp256k1.verify(signature, message, pubKey);
54

55
// EdDSA with Ed25519
56
const ed25519PrivKey = ed25519.utils.randomPrivateKey();
57
const ed25519PubKey = ed25519.getPublicKey(ed25519PrivKey);
58

59
const ed25519Sig = ed25519.sign(message, ed25519PrivKey);
60
const ed25519Valid = ed25519.verify(ed25519Sig, message, ed25519PubKey);
61

62
// Key exchange with X25519
63
import { x25519 } from "@noble/curves/ed25519";
64

65
const alicePriv = x25519.utils.randomPrivateKey();
66
const alicePub = x25519.getPublicKey(alicePriv);
67

68
const bobPriv = x25519.utils.randomPrivateKey();
69
const bobPub = x25519.getPublicKey(bobPriv);
70

71
const sharedSecret1 = x25519.getSharedSecret(alicePriv, bobPub);
72
const sharedSecret2 = x25519.getSharedSecret(bobPriv, alicePub);
73
// sharedSecret1 === sharedSecret2
74
```
75

76
## Architecture
77

78
@noble/curves is built around several key architectural components:
79

80
- **Modular Design**: Each curve can be imported independently for optimal tree-shaking
81
- **Abstract Primitives**: Foundational building blocks (weierstrass, edwards, modular arithmetic) for constructing custom curves  
82
- **Type Safety**: Full TypeScript integration with comprehensive type definitions
83
- **Security Focus**: Constant-time algorithms where possible, independent security audits
84
- **Standards Compliance**: Implements RFC and standardized algorithms (BIP340 Schnorr, RFC 8032 EdDSA, etc.)
85

86
## Capabilities
87

88
### Elliptic Curve Implementations
89

90
Complete implementations of popular elliptic curves with signature schemes and key exchange protocols. Each curve provides signing, verification, key generation, and point operations.
91

92
```typescript { .api }
93
// Common curve interface
94
interface CurveFn {
95
  getPublicKey(privateKey: PrivKey): Uint8Array;
96
  sign(message: Hex, privateKey: PrivKey): ECDSASignature;
97
  verify(signature: ECDSASignature, message: Hex, publicKey: Hex): boolean;
98
  Point: WeierstrassPointCons<bigint>;
99
  Signature: ECDSASignatureCons;
100
  utils: {
101
    randomPrivateKey(): Uint8Array;
102
    precompute(windowSize?: number, point?: WeierstrassPoint<bigint>): WeierstrassPoint<bigint>;
103
  };
104
}
105
```
106

107
[Curve Implementations](./curves.md)
108

109
### Abstract Cryptographic Primitives
110

111
Low-level building blocks for implementing custom elliptic curves, including field arithmetic, point operations, signature schemes, and hash-to-curve functionality.
112

113
```typescript { .api }
114
// Core abstract functions
115
function weierstrass(c: CurveType): CurveFn;
116
function twistedEdwards(c: CurveTypeWithLength): CurveFn;
117
function Field(ORDER: bigint, opts?: FieldOpts): IField<bigint>;
118
function ecdsa(Point: WeierstrassPointCons, Hash: CHash, opts?: ECDSAOpts): ECDSA;
119
function eddsa(Point: EdwardsPointCons, cHash: FHash, opts?: EdDSAOpts): EdDSA;
120
```
121

122
[Abstract Primitives](./abstract-primitives.md)
123

124
### Cryptographic Utilities
125

126
Essential utility functions for byte manipulation, number conversion, validation, and cryptographic operations used throughout the library.
127

128
```typescript { .api }
129
// Core utility functions  
130
function bytesToHex(bytes: Uint8Array): string;
131
function hexToBytes(hex: string): Uint8Array;
132
function concatBytes(...arrays: Uint8Array[]): Uint8Array;
133
function randomBytes(bytesLength?: number): Uint8Array;
134
function mod(a: bigint, b: bigint): bigint;
135
function invert(number: bigint, modulo: bigint): bigint;
136
```
137

138
[Utilities](./utilities.md)
139

140
### WebCrypto Integration
141

142
Native browser WebCrypto API wrappers providing hardware-accelerated elliptic curve operations with the same API as main curve implementations.
143

144
```typescript { .api }
145
// WebCrypto curve interfaces
146
interface WebCryptoNIST extends WebCryptoBaseCurve, WebCryptoSigner, WebCryptoECDH;
147
interface WebCryptoEdDSA extends WebCryptoBaseCurve, WebCryptoSigner;
148
interface WebCryptoMontgomery extends WebCryptoBaseCurve, WebCryptoECDH;
149

150
// Check curve availability
151
function supportsWc(curve: WebCryptoBaseCurve): Promise<boolean>;
152
```
153

154
[WebCrypto Integration](./webcrypto.md)
155

156
## Types
157

158
### Core Types
159

160
```typescript { .api }
161
type Hex = Uint8Array | string;
162
type PrivKey = Hex | bigint;
163

164
interface CHash {
165
  (message: Uint8Array): Uint8Array;
166
  blockLen: number;
167
  outputLen: number;
168
  create(): any;
169
}
170

171
interface FHash {
172
  (message: Uint8Array | string): Uint8Array;
173
}
174
```
175

176
### Signature Types
177

178
```typescript { .api }
179
interface ECDSASignature {
180
  r: bigint;
181
  s: bigint;
182
  recovery?: number;
183
  toCompactRawBytes(): Uint8Array;
184
  toDERRawBytes(): Uint8Array;
185
}
186

187
interface EdDSA {
188
  sign(message: Hex, privateKey: PrivKey): Uint8Array;
189
  verify(signature: Hex, message: Hex, publicKey: Hex): boolean;
190
  getPublicKey(privateKey: PrivKey): Uint8Array;
191
}
192
```
193

194
### Field and Point Types
195

196
```typescript { .api }
197
interface IField<T> {
198
  ORDER: bigint;
199
  ZERO: T;
200
  ONE: T;
201
  create(num: T): T;
202
  add(a: T, b: T): T;
203
  mul(a: T, b: T): T;
204
  pow(a: T, b: bigint): T;
205
  inv(a: T): T;
206
  sqrt(a: T): T;
207
  eql(a: T, b: T): boolean;
208
}
209

210
interface WeierstrassPoint<T> {
211
  x: T;
212
  y: T;
213
  z: T;
214
  add(other: WeierstrassPoint<T>): WeierstrassPoint<T>;
215
  multiply(scalar: bigint): WeierstrassPoint<T>;
216
  toAffine(): { x: T; y: T };
217
  toRawBytes(isCompressed?: boolean): Uint8Array;
218
}
219

220
interface EdwardsPoint {
221
  x: bigint;
222
  y: bigint;
223
  z: bigint;
224
  t: bigint;
225
  add(other: EdwardsPoint): EdwardsPoint;
226
  multiply(scalar: bigint): EdwardsPoint;
227
  toAffine(): { x: bigint; y: bigint };
228
  toRawBytes(): Uint8Array;
229
}
230
```