0
# StarkEx Protocol
1

2
Complete support for StarkEx layer 2 protocol operations including public key generation, order signing, transfer signing, and quantum provisioning. The library supports both v1 and v2 StarkEx protocols with comprehensive token type support.
3

4
## Capabilities
5

6
### Public Key Generation
7

8
Generate StarkEx public keys for layer 2 operations.
9

10
```typescript { .api }
11
/**
12
 * Get StarkEx public key for a given BIP32 path
13
 * @param path - BIP32 derivation path for StarkEx key
14
 * @param boolDisplay - Optionally display key on device screen
15
 * @returns StarkEx public key as Buffer
16
 */
17
starkGetPublicKey(path: string, boolDisplay?: boolean): Promise<Buffer>;
18
```
19

20
**Usage Example:**
21

22
```typescript
23
// Generate StarkEx public key
24
const publicKey = await eth.starkGetPublicKey("44'/60'/0'/0/0");
25
console.log(publicKey.toString("hex")); // StarkEx public key
26

27
// Display public key on device for verification
28
const publicKey = await eth.starkGetPublicKey("44'/60'/0'/0/0", true);
29
```
30

31
### Order Signing (v1)
32

33
Sign StarkEx orders using the original v1 protocol.
34

35
```typescript { .api }
36
/**
37
 * Sign StarkEx order using v1 protocol
38
 * @param path - BIP32 derivation path for signing key
39
 * @param sourceTokenAddress - Source token contract address (undefined for ETH)
40
 * @param sourceQuantization - Source token quantization unit
41
 * @param destinationTokenAddress - Destination token contract address (undefined for ETH)
42
 * @param destinationQuantization - Destination token quantization unit
43
 * @param sourceVault - Source vault ID
44
 * @param destinationVault - Destination vault ID
45
 * @param amountSell - Amount to sell in quantized units
46
 * @param amountBuy - Amount to buy in quantized units
47
 * @param nonce - Order nonce
48
 * @param timestamp - Order expiration timestamp
49
 * @returns Order signature as Buffer or signature components
50
 */
51
starkSignOrder(
52
  path: string,
53
  sourceTokenAddress: string | undefined,
54
  sourceQuantization: BigNumber,
55
  destinationTokenAddress: string | undefined,
56
  destinationQuantization: BigNumber,
57
  sourceVault: number,
58
  destinationVault: number,
59
  amountSell: BigNumber,
60
  amountBuy: BigNumber,
61
  nonce: number,
62
  timestamp: number
63
): Promise<Buffer | {r: string; s: string}>;
64
```
65

66
### Order Signing (v2)
67

68
Sign StarkEx orders using the enhanced v2 protocol with extended token type support.
69

70
```typescript { .api }
71
/**
72
 * Sign StarkEx order using v2 protocol with enhanced token support
73
 * @param path - BIP32 derivation path for signing key
74
 * @param sourceTokenAddress - Source token contract address (undefined for ETH)
75
 * @param sourceQuantizationType - Source token type classification
76
 * @param sourceQuantization - Source token quantization unit (undefined for some types)
77
 * @param sourceMintableBlobOrTokenId - Token ID or blob for mintable tokens
78
 * @param destinationTokenAddress - Destination token contract address (undefined for ETH)
79
 * @param destinationQuantizationType - Destination token type classification
80
 * @param destinationQuantization - Destination token quantization unit (undefined for some types)
81
 * @param destinationMintableBlobOrTokenId - Token ID or blob for mintable tokens
82
 * @param sourceVault - Source vault ID
83
 * @param destinationVault - Destination vault ID
84
 * @param amountSell - Amount to sell in quantized units
85
 * @param amountBuy - Amount to buy in quantized units
86
 * @param nonce - Order nonce
87
 * @param timestamp - Order expiration timestamp
88
 * @returns Order signature as Buffer or signature components
89
 */
90
starkSignOrder_v2(
91
  path: string,
92
  sourceTokenAddress: string | undefined,
93
  sourceQuantizationType: StarkQuantizationType,
94
  sourceQuantization: BigNumber | undefined,
95
  sourceMintableBlobOrTokenId: BigNumber | undefined,
96
  destinationTokenAddress: string | undefined,
97
  destinationQuantizationType: StarkQuantizationType,
98
  destinationQuantization: BigNumber | undefined,
99
  destinationMintableBlobOrTokenId: BigNumber | undefined,
100
  sourceVault: number,
101
  destinationVault: number,
102
  amountSell: BigNumber,
103
  amountBuy: BigNumber,
104
  nonce: number,
105
  timestamp: number
106
): Promise<Buffer | {r: string; s: string}>;
107
```
108

109
**Usage Examples:**
110

111
```typescript
112
import { BigNumber } from "bignumber.js";
113

114
// Sign ETH to ERC20 order (v1)
115
const signature = await eth.starkSignOrder(
116
  "44'/60'/0'/0/0",
117
  undefined, // ETH (no token address)
118
  new BigNumber("1000000000000000000"), // 1 ETH quantization
119
  "0xA0b86a33E6776a9fEddac4F0c0bfB3F4a9d7d3e7", // USDC token
120
  new BigNumber("1000000"), // USDC quantization (6 decimals)
121
  12345, // Source vault
122
  67890, // Destination vault
123
  new BigNumber("1000000000000000000"), // Sell 1 ETH
124
  new BigNumber("3000000000"), // Buy 3000 USDC
125
  1, // Nonce
126
  Math.floor(Date.now() / 1000) + 3600 // Expires in 1 hour
127
);
128

129
// Sign ERC721 to ERC20 order (v2)
130
const signature = await eth.starkSignOrder_v2(
131
  "44'/60'/0'/0/0",
132
  "0x1234567890123456789012345678901234567890", // NFT contract
133
  "erc721", // Source is ERC721
134
  undefined, // No quantization for ERC721
135
  new BigNumber("42"), // Token ID
136
  "0xA0b86a33E6776a9fEddac4F0c0bfB3F4a9d7d3e7", // USDC token
137
  "erc20", // Destination is ERC20
138
  new BigNumber("1000000"), // USDC quantization
139
  undefined, // No token ID for ERC20
140
  111, // Source vault
141
  222, // Destination vault
142
  new BigNumber("1"), // Sell 1 NFT
143
  new BigNumber("500000000"), // Buy 500 USDC
144
  5, // Nonce
145
  Math.floor(Date.now() / 1000) + 7200 // Expires in 2 hours
146
);
147
```
148

149
### Transfer Signing (v1)
150

151
Sign StarkEx transfers using the original v1 protocol.
152

153
```typescript { .api }
154
/**
155
 * Sign StarkEx transfer using v1 protocol
156
 * @param path - BIP32 derivation path for signing key
157
 * @param transferTokenAddress - Token contract address (undefined for ETH)
158
 * @param transferQuantization - Token quantization unit
159
 * @param targetPublicKey - Recipient's StarkEx public key
160
 * @param sourceVault - Source vault ID
161
 * @param destinationVault - Destination vault ID
162
 * @param amountTransfer - Amount to transfer in quantized units
163
 * @param nonce - Transfer nonce
164
 * @param timestamp - Transfer expiration timestamp
165
 * @returns Transfer signature as Buffer or signature components
166
 */
167
starkSignTransfer(
168
  path: string,
169
  transferTokenAddress: string | undefined,
170
  transferQuantization: BigNumber,
171
  targetPublicKey: string,
172
  sourceVault: number,
173
  destinationVault: number,
174
  amountTransfer: BigNumber,
175
  nonce: number,
176
  timestamp: number
177
): Promise<Buffer | {r: string; s: string}>;
178
```
179

180
### Transfer Signing (v2)
181

182
Sign StarkEx transfers using the enhanced v2 protocol with conditional transfer support.
183

184
```typescript { .api }
185
/**
186
 * Sign StarkEx transfer using v2 protocol with enhanced features
187
 * @param path - BIP32 derivation path for signing key
188
 * @param transferTokenAddress - Token contract address (undefined for ETH)
189
 * @param transferQuantizationType - Token type classification
190
 * @param transferQuantization - Token quantization unit (undefined for some types)
191
 * @param transferMintableBlobOrTokenId - Token ID or blob for mintable tokens
192
 * @param targetPublicKey - Recipient's StarkEx public key
193
 * @param sourceVault - Source vault ID
194
 * @param destinationVault - Destination vault ID
195
 * @param amountTransfer - Amount to transfer in quantized units
196
 * @param nonce - Transfer nonce
197
 * @param timestamp - Transfer expiration timestamp
198
 * @param conditionalTransferAddress - Optional conditional transfer contract address
199
 * @param conditionalTransferFact - Optional conditional transfer fact
200
 * @returns Transfer signature as Buffer or signature components
201
 */
202
starkSignTransfer_v2(
203
  path: string,
204
  transferTokenAddress: string | undefined,
205
  transferQuantizationType: StarkQuantizationType,
206
  transferQuantization: BigNumber | undefined,
207
  transferMintableBlobOrTokenId: BigNumber | undefined,
208
  targetPublicKey: string,
209
  sourceVault: number,
210
  destinationVault: number,
211
  amountTransfer: BigNumber,
212
  nonce: number,
213
  timestamp: number,
214
  conditionalTransferAddress?: string,
215
  conditionalTransferFact?: BigNumber
216
): Promise<Buffer | {r: string; s: string}>;
217
```
218

219
**Usage Examples:**
220

221
```typescript
222
// Sign ETH transfer (v1)
223
const signature = await eth.starkSignTransfer(
224
  "44'/60'/0'/0/0",
225
  undefined, // ETH
226
  new BigNumber("1000000000000000000"), // 1 ETH quantization
227
  "0x1234567890abcdef...", // Recipient's StarkEx public key
228
  111, // Source vault
229
  222, // Destination vault
230
  new BigNumber("500000000000000000"), // Transfer 0.5 ETH
231
  10, // Nonce
232
  Math.floor(Date.now() / 1000) + 3600 // Expires in 1 hour
233
);
234

235
// Sign conditional ERC721 transfer (v2)
236
const signature = await eth.starkSignTransfer_v2(
237
  "44'/60'/0'/0/0",
238
  "0x1234567890123456789012345678901234567890", // NFT contract
239
  "erc721", // Token type
240
  undefined, // No quantization for ERC721
241
  new BigNumber("123"), // Token ID
242
  "0xabcdef1234567890...", // Recipient's public key
243
  333, // Source vault
244
  444, // Destination vault
245
  new BigNumber("1"), // Transfer 1 NFT
246
  15, // Nonce
247
  Math.floor(Date.now() / 1000) + 7200, // Expires in 2 hours
248
  "0xConditionalContract123...", // Conditional transfer contract
249
  new BigNumber("999") // Transfer condition fact
250
);
251
```
252

253
### Quantum Provisioning
254

255
Provide quantum information to the hardware wallet for StarkEx operations.
256

257
```typescript { .api }
258
/**
259
 * Provide quantum information for StarkEx operations (v1)
260
 * @param operationContract - Token contract address (undefined for ETH)
261
 * @param operationQuantization - Token quantization unit
262
 * @returns Success status
263
 */
264
starkProvideQuantum(
265
  operationContract: string | undefined,
266
  operationQuantization: BigNumber
267
): Promise<boolean>;
268

269
/**
270
 * Provide quantum information for StarkEx operations (v2)
271
 * @param operationContract - Token contract address (undefined for ETH)
272
 * @param operationQuantizationType - Token type classification
273
 * @param operationQuantization - Token quantization unit (undefined for some types)
274
 * @param operationMintableBlobOrTokenId - Token ID or blob for mintable tokens
275
 * @returns Success status
276
 */
277
starkProvideQuantum_v2(
278
  operationContract: string | undefined,
279
  operationQuantizationType: StarkQuantizationType,
280
  operationQuantization?: BigNumber,
281
  operationMintableBlobOrTokenId?: BigNumber
282
): Promise<boolean>;
283
```
284

285
**Usage Examples:**
286

287
```typescript
288
// Provide ETH quantum (v1)
289
await eth.starkProvideQuantum(
290
  undefined, // ETH
291
  new BigNumber("1000000000000000000") // 1 ETH quantization
292
);
293

294
// Provide ERC721 quantum (v2)
295
await eth.starkProvideQuantum_v2(
296
  "0x1234567890123456789012345678901234567890", // NFT contract
297
  "erc721", // Token type
298
  undefined, // No quantization for ERC721
299
  new BigNumber("456") // Token ID
300
);
301
```
302

303
### Unsafe Signing
304

305
Sign arbitrary StarkEx hashes for advanced use cases.
306

307
```typescript { .api }
308
/**
309
 * Sign arbitrary hash using StarkEx unsafe signing (advanced use only)
310
 * @param path - BIP32 derivation path for signing key
311
 * @param hash - Hash to sign as hex string
312
 * @returns Signature as Buffer or signature components
313
 */
314
starkUnsafeSign(path: string, hash: string): Promise<Buffer | {r: string; s: string}>;
315
```
316

317
**Usage Example:**
318

319
```typescript
320
// Advanced: Sign pre-computed hash
321
const hash = "0x1234567890abcdef..."; // Pre-computed StarkEx operation hash
322
const signature = await eth.starkUnsafeSign("44'/60'/0'/0/0", hash);
323
```
324

325
## StarkEx Types
326

327
```typescript { .api }
328
/**
329
 * StarkEx token quantization types for v2 protocol
330
 */
331
type StarkQuantizationType = 
332
  | "eth"           // Native ETH
333
  | "erc20"         // ERC20 fungible tokens
334
  | "erc721"        // ERC721 non-fungible tokens
335
  | "erc20mintable" // Mintable ERC20 tokens
336
  | "erc721mintable"; // Mintable ERC721 tokens
337
```
338

339
## Protocol Compatibility
340

341
The library supports both StarkEx v1 and v2 protocols:
342

343
- **v1 Protocol**: Basic token support (ETH, ERC20, simple ERC721)
344
- **v2 Protocol**: Enhanced features including:
345
  - Mintable token support
346
  - Extended token type system
347
  - Conditional transfers
348
  - Improved token ID handling
349
  - Better quantization support
350

351
**Migration from v1 to v2:**
352

353
```typescript
354
// v1 approach
355
await eth.starkSignOrder(
356
  path, tokenAddr, quantization, /* ... */
357
);
358

359
// v2 approach with equivalent functionality
360
await eth.starkSignOrder_v2(
361
  path, tokenAddr, "erc20", quantization, undefined, /* ... */
362
);
363
```