0
# Point Operations
1

2
Complete Edwards curve point arithmetic for advanced cryptographic operations and custom implementations. The Point class provides efficient operations in extended XYZT coordinates for the ed25519 twisted Edwards curve.
3

4
## Capabilities
5

6
### Point Class
7

8
The main Point class for edwards curve operations, representing points in XYZT extended coordinates.
9

10
```typescript { .api }
11
/**
12
 * Point in XYZT extended coordinates for efficient elliptic curve operations
13
 * Represents points on the ed25519 twisted Edwards curve: -x² + y² = -1 + dx²y²
14
 */
15
class Point {
16
  /** Base/generator point of the ed25519 curve */
17
  static readonly BASE: Point;
18
  
19
  /** Zero/identity point of the curve */
20
  static readonly ZERO: Point;
21
  
22
  /** Extended coordinate values */
23
  readonly X: bigint;
24
  readonly Y: bigint;
25
  readonly Z: bigint;
26
  readonly T: bigint;
27
  
28
  /**
29
   * Create new Point instance with XYZT extended coordinates
30
   * @param X - X coordinate
31
   * @param Y - Y coordinate  
32
   * @param Z - Z coordinate
33
   * @param T - T coordinate
34
   */
35
  constructor(X: bigint, Y: bigint, Z: bigint, T: bigint);
36
  
37
  /** Affine x coordinate (computed from X/Z) */
38
  get x(): bigint;
39
  
40
  /** Affine y coordinate (computed from Y/Z) */
41
  get y(): bigint;
42
}
43
```
44

45
### Static Methods
46

47
Factory methods for creating Point instances from various representations.
48

49
```typescript { .api }
50
/**
51
 * Get curve parameters for ed25519
52
 * @returns Edwards curve parameters including field prime, group order, coefficients
53
 */
54
static CURVE(): EdwardsOpts;
55

56
/**
57
 * Create point from affine coordinates
58
 * @param p - Affine point with x, y coordinates
59
 * @returns Point in extended coordinates
60
 */
61
static fromAffine(p: AffinePoint): Point;
62

63
/**
64
 * Create point from 32-byte representation (RFC8032 section 5.1.3)
65
 * @param hex - 32-byte point encoding
66
 * @param zip215 - Enable ZIP215 compliance for non-canonical encodings
67
 * @returns Point instance
68
 */
69
static fromBytes(hex: Bytes, zip215?: boolean): Point;
70

71
/**
72
 * Create point from hex string representation
73
 * @param hex - Hex-encoded point (64 characters)
74
 * @param zip215 - Enable ZIP215 compliance for non-canonical encodings
75
 * @returns Point instance
76
 */
77
static fromHex(hex: string, zip215?: boolean): Point;
78
```
79

80
**Usage Examples:**
81

82
```typescript
83
import { Point } from '@noble/ed25519';
84

85
// Access curve constants
86
const basePoint = Point.BASE;
87
const zeroPoint = Point.ZERO;
88
const curveParams = Point.CURVE();
89

90
// Create from affine coordinates
91
const affinePoint = Point.fromAffine({ x: 15112221349535400772501151409588531511454012693041857206046113283949847762202n, y: 46316835694926478169428394003475163141307993866256225615783033603165251855960n });
92

93
// Create from bytes
94
const bytes = new Uint8Array(32);
95
bytes[31] = 0x58; // Set y-coordinate and sign bit
96
const pointFromBytes = Point.fromBytes(bytes);
97

98
// Create from hex
99
const pointFromHex = Point.fromHex('5866666666666666666666666666666666666666666666666666666666666666');
100
```
101

102
### Instance Methods
103

104
Arithmetic operations and point manipulations.
105

106
```typescript { .api }
107
/**
108
 * Validate that point lies on the curve
109
 * @throws Error if point is not on curve
110
 * @returns This point for chaining
111
 */
112
assertValidity(): this;
113

114
/**
115
 * Check if two points are equal
116
 * @param other - Point to compare with
117
 * @returns True if points are equal
118
 */
119
equals(other: Point): boolean;
120

121
/**
122
 * Check if point is the zero/identity point
123
 * @returns True if point is zero
124
 */
125
is0(): boolean;
126

127
/**
128
 * Negate point by flipping it over the y-coordinate
129
 * @returns Negated point
130
 */
131
negate(): Point;
132

133
/**
134
 * Point doubling operation
135
 * @returns 2 * this point
136
 */
137
double(): Point;
138

139
/**
140
 * Point addition
141
 * @param other - Point to add
142
 * @returns this + other
143
 */
144
add(other: Point): Point;
145

146
/**
147
 * Point subtraction  
148
 * @param other - Point to subtract
149
 * @returns this - other
150
 */
151
subtract(other: Point): Point;
152

153
/**
154
 * Scalar multiplication (primary operation for cryptographic protocols)
155
 * @param n - Scalar multiplier
156
 * @param safe - Use safe multiplication algorithm (default: true)
157
 * @returns n * this point
158
 */
159
multiply(n: bigint, safe?: boolean): Point;
160

161
/**
162
 * Unsafe scalar multiplication (faster but potentially vulnerable to timing attacks)
163
 * @param scalar - Scalar multiplier
164
 * @returns scalar * this point
165
 */
166
multiplyUnsafe(scalar: bigint): Point;
167
```
168

169
**Usage Examples:**
170

171
```typescript
172
import { Point } from '@noble/ed25519';
173

174
const p1 = Point.BASE;
175
const p2 = Point.BASE.double();
176

177
// Basic operations
178
const sum = p1.add(p2);
179
const difference = p2.subtract(p1);
180
const doubled = p1.double();
181
const negated = p1.negate();
182

183
// Scalar multiplication
184
const scalar = 12345678901234567890n;
185
const multiplied = p1.multiply(scalar);
186

187
// Fast unsafe multiplication (use with caution)
188
const fastMultiplied = p1.multiplyUnsafe(scalar);
189

190
// Point validation
191
try {
192
  p1.assertValidity(); // Should not throw for valid points
193
} catch (error) {
194
  console.log('Invalid point');
195
}
196

197
// Equality check
198
console.log(p1.equals(Point.BASE)); // true
199
console.log(Point.ZERO.is0()); // true
200
```
201

202
### Coordinate Conversion
203

204
Methods for converting between coordinate systems and encodings.
205

206
```typescript { .api }
207
/**
208
 * Convert to affine coordinates
209
 * @returns Affine point with x, y coordinates
210
 */
211
toAffine(): AffinePoint;
212

213
/**
214
 * Convert to 32-byte representation (RFC8032 section 5.1.2)
215
 * @returns 32-byte point encoding
216
 */
217
toBytes(): Bytes;
218

219
/**
220
 * Convert to hex string representation
221
 * @returns 64-character hex string
222
 */
223
toHex(): string;
224
```
225

226
### Advanced Operations
227

228
Specialized operations for cryptographic protocols and curve analysis.
229

230
```typescript { .api }
231
/**
232
 * Clear cofactor by multiplying by cofactor (8 for ed25519)
233
 * @returns Point with cleared cofactor
234
 */
235
clearCofactor(): Point;
236

237
/**
238
 * Check if point has small order (order divides cofactor)
239
 * @returns True if point has small order
240
 */
241
isSmallOrder(): boolean;
242

243
/**
244
 * Check if point is torsion-free (order is not divisible by cofactor)
245
 * @returns True if point is torsion-free
246
 */
247
isTorsionFree(): boolean;
248
```
249

250
**Usage Examples:**
251

252
```typescript
253
import { Point } from '@noble/ed25519';
254

255
const point = Point.BASE.multiply(123n);
256

257
// Coordinate conversion
258
const affine = point.toAffine();
259
console.log(`x: ${affine.x}, y: ${affine.y}`);
260

261
const bytes = point.toBytes();
262
console.log(`Point as bytes: ${bytes.length} bytes`);
263

264
const hex = point.toHex();
265
console.log(`Point as hex: ${hex}`);
266

267
// Round-trip conversion
268
const restored = Point.fromHex(hex);
269
console.log(point.equals(restored)); // true
270

271
// Advanced operations
272
const clearedCofactor = point.clearCofactor();
273
const hasSmallOrder = point.isSmallOrder();
274
const isTorsionFree = point.isTorsionFree();
275

276
console.log(`Small order: ${hasSmallOrder}, Torsion-free: ${isTorsionFree}`);
277
```
278

279
## Error Handling
280

281
Point operations throw errors for invalid inputs or operations:
282

283
- Invalid point coordinates (not on curve)
284
- Invalid byte/hex encoding length
285
- Invalid scalar values for multiplication
286
- Operations on invalid points
287

288
```typescript
289
import { Point } from '@noble/ed25519';
290

291
try {
292
  // Invalid hex length
293
  Point.fromHex('invalid');
294
} catch (error) {
295
  console.log('Invalid hex encoding');
296
}
297

298
try {
299
  // Invalid point that's not on curve
300
  const invalidPoint = Point.fromAffine({ x: 0n, y: 0n });
301
  invalidPoint.assertValidity(); // Will throw
302
} catch (error) {
303
  console.log('Point not on curve');
304
}
305
```
306

307
## Types
308

309
```typescript { .api }
310
type Bytes = Uint8Array;
311

312
type AffinePoint = {
313
  x: bigint;
314
  y: bigint;
315
};
316

317
type EdwardsOpts = Readonly<{
318
  /** Field prime */
319
  p: bigint;
320
  /** Group order */
321
  n: bigint; 
322
  /** Cofactor */
323
  h: bigint;
324
  /** Curve parameter a */
325
  a: bigint;
326
  /** Curve parameter d */
327
  d: bigint;
328
  /** Generator x-coordinate */
329
  Gx: bigint;
330
  /** Generator y-coordinate */
331
  Gy: bigint;
332
}>;
333
```