@provablehq/sdk 0.9.16-rc → 0.9.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/dist/mainnet/account.d.ts +18 -3
  2. package/dist/mainnet/browser.d.ts +26 -7
  3. package/dist/mainnet/browser.js +1198 -248
  4. package/dist/mainnet/browser.js.map +1 -1
  5. package/dist/mainnet/keys/keystore/error.d.ts +23 -0
  6. package/dist/mainnet/keys/keystore/file.d.ts +207 -13
  7. package/dist/mainnet/keys/keystore/interface.d.ts +85 -0
  8. package/dist/mainnet/keys/provider/interface.d.ts +170 -0
  9. package/dist/{testnet/keys/provider/function-key-provider.d.ts → mainnet/keys/provider/memory.d.ts} +14 -180
  10. package/dist/{testnet/keys/provider/offline-key-provider.d.ts → mainnet/keys/provider/offline.d.ts} +4 -4
  11. package/dist/mainnet/keys/verifier/interface.d.ts +70 -0
  12. package/dist/mainnet/keys/verifier/memory.d.ts +37 -0
  13. package/dist/mainnet/models/cryptoBoxPubkey.d.ts +4 -0
  14. package/dist/mainnet/models/encryptedProvingRequest.d.ts +4 -0
  15. package/dist/mainnet/models/provingResponse.d.ts +48 -2
  16. package/dist/mainnet/models/record-scanner/encryptedRecordsResult.d.ts +7 -0
  17. package/dist/mainnet/models/record-scanner/encryptedRegistrationRequest.d.ts +8 -0
  18. package/dist/mainnet/models/record-scanner/error.d.ts +47 -0
  19. package/dist/mainnet/models/record-scanner/ownedFilter.d.ts +0 -2
  20. package/dist/mainnet/models/record-scanner/ownedRecordsResult.d.ts +13 -0
  21. package/dist/mainnet/models/record-scanner/registrationResponse.d.ts +0 -2
  22. package/dist/mainnet/models/record-scanner/registrationResult.d.ts +9 -0
  23. package/dist/mainnet/models/record-scanner/revokeResult.d.ts +17 -0
  24. package/dist/mainnet/models/record-scanner/serialNumbersResult.d.ts +15 -0
  25. package/dist/mainnet/models/record-scanner/statusResult.d.ts +13 -0
  26. package/dist/mainnet/models/record-scanner/tagsResult.d.ts +12 -0
  27. package/dist/mainnet/network-client.d.ts +81 -35
  28. package/dist/mainnet/node.js +345 -75
  29. package/dist/mainnet/node.js.map +1 -1
  30. package/dist/mainnet/program-manager.d.ts +54 -48
  31. package/dist/mainnet/record-provider.d.ts +7 -7
  32. package/dist/mainnet/record-scanner.d.ts +247 -31
  33. package/dist/mainnet/security.d.ts +38 -0
  34. package/dist/mainnet/utils.d.ts +1 -0
  35. package/dist/testnet/account.d.ts +18 -3
  36. package/dist/testnet/browser.d.ts +26 -7
  37. package/dist/testnet/browser.js +1198 -248
  38. package/dist/testnet/browser.js.map +1 -1
  39. package/dist/testnet/keys/keystore/error.d.ts +23 -0
  40. package/dist/testnet/keys/keystore/file.d.ts +207 -13
  41. package/dist/testnet/keys/keystore/interface.d.ts +85 -0
  42. package/dist/testnet/keys/provider/interface.d.ts +170 -0
  43. package/dist/{mainnet/keys/provider/function-key-provider.d.ts → testnet/keys/provider/memory.d.ts} +14 -180
  44. package/dist/{mainnet/keys/provider/offline-key-provider.d.ts → testnet/keys/provider/offline.d.ts} +4 -4
  45. package/dist/testnet/keys/verifier/interface.d.ts +70 -0
  46. package/dist/testnet/keys/verifier/memory.d.ts +37 -0
  47. package/dist/testnet/models/cryptoBoxPubkey.d.ts +4 -0
  48. package/dist/testnet/models/encryptedProvingRequest.d.ts +4 -0
  49. package/dist/testnet/models/provingResponse.d.ts +48 -2
  50. package/dist/testnet/models/record-scanner/encryptedRecordsResult.d.ts +7 -0
  51. package/dist/testnet/models/record-scanner/encryptedRegistrationRequest.d.ts +8 -0
  52. package/dist/testnet/models/record-scanner/error.d.ts +47 -0
  53. package/dist/testnet/models/record-scanner/ownedFilter.d.ts +0 -2
  54. package/dist/testnet/models/record-scanner/ownedRecordsResult.d.ts +13 -0
  55. package/dist/testnet/models/record-scanner/registrationResponse.d.ts +0 -2
  56. package/dist/testnet/models/record-scanner/registrationResult.d.ts +9 -0
  57. package/dist/testnet/models/record-scanner/revokeResult.d.ts +17 -0
  58. package/dist/testnet/models/record-scanner/serialNumbersResult.d.ts +15 -0
  59. package/dist/testnet/models/record-scanner/statusResult.d.ts +13 -0
  60. package/dist/testnet/models/record-scanner/tagsResult.d.ts +12 -0
  61. package/dist/testnet/network-client.d.ts +81 -35
  62. package/dist/testnet/node.js +345 -75
  63. package/dist/testnet/node.js.map +1 -1
  64. package/dist/testnet/program-manager.d.ts +54 -48
  65. package/dist/testnet/record-provider.d.ts +7 -7
  66. package/dist/testnet/record-scanner.d.ts +247 -31
  67. package/dist/testnet/security.d.ts +38 -0
  68. package/dist/testnet/utils.d.ts +1 -0
  69. package/package.json +4 -3
  70. package/dist/mainnet/keys/keystore/keystore.d.ts +0 -81
  71. package/dist/mainnet/keys/keystore/memory.d.ts +0 -8
  72. package/dist/testnet/keys/keystore/keystore.d.ts +0 -81
  73. package/dist/testnet/keys/keystore/memory.d.ts +0 -8
@@ -1,28 +1,67 @@
1
1
  import { EncryptedRecord } from "./models/record-provider/encryptedRecord";
2
+ import { CryptoBoxPubKey } from "./models/cryptoBoxPubkey.js";
2
3
  import { OwnedFilter } from "./models/record-scanner/ownedFilter";
3
4
  import { OwnedRecord } from "./models/record-provider/ownedRecord";
4
5
  import { RecordProvider } from "./record-provider";
5
6
  import { Field, ViewKey } from "./wasm";
6
7
  import { RecordsFilter } from "./models/record-scanner/recordsFilter";
7
- import { RegistrationResponse } from "./models/record-scanner/registrationResponse";
8
- import { StatusResponse } from "./models/record-scanner/statusResponse";
9
- type RecordScannerOptions = {
8
+ import { RegisterResult } from "./models/record-scanner/registrationResult.js";
9
+ import { RevokeResult } from "./models/record-scanner/revokeResult.js";
10
+ import { TagsResult } from "./models/record-scanner/tagsResult.js";
11
+ import { SerialNumbersResult } from "./models/record-scanner/serialNumbersResult.js";
12
+ import { StatusResult } from "./models/record-scanner/statusResult.js";
13
+ import { OwnedRecordsResult } from "./models/record-scanner/ownedRecordsResult.js";
14
+ import { EncryptedRecordsResult } from "./models/record-scanner/encryptedRecordsResult.js";
15
+ import { Account } from "./account.js";
16
+ /**
17
+ * JWT data for optional authentication with the record scanning service (e.g. Provable API).
18
+ *
19
+ * @property {string} jwt The JWT token string.
20
+ * @property {number} expiration Expiration time as a Unix timestamp (e.g. in milliseconds).
21
+ */
22
+ export interface RecordScannerJWTData {
23
+ jwt: string;
24
+ expiration: number;
25
+ }
26
+ /**
27
+ * Configuration for the record scanner.
28
+ *
29
+ * @property {string} url Base URL of the record scanning service (network path is appended by the SDK).
30
+ * @property {string | { header: string, value: string }} [apiKey] API key as a string or as a custom header name and value.
31
+ * @property {string} [consumerId] Required for JWT refresh when using authenticated record scanner (e.g. Provable API).
32
+ * @property {RecordScannerJWTData} [jwtData] Optional JWT for auth. If omitted and apiKey + consumerId are set, JWT is refreshed when needed.
33
+ * @property {ViewKey[]} [viewKeys] Optional view keys to use for local scanning and decryption.
34
+ * @property {Account} [account] Optional account to use for local scanning and decryption.
35
+ * @property {boolean} [cacheViewKeysOnRegister] Cache view keys in memory for faster scanning upon register.
36
+ * @property {boolean} [autoReRegister] If true, on 422 from /owned attempt one re-register via registerEncrypted (when a view key is in viewKeys or account) and retry once. Default false.
37
+ * @property {boolean} [decryptEnabled] If true, enable decryption of owned records (e.g. for use with the decrypt method). This is REQUIRED for findCreditsRecord/findCreditsRecords to work properly. Further the ViewKey matching the UUID must be stored in the RecordScanner object to perform decryption. Default false.
38
+ */
39
+ export interface RecordScannerOptions {
10
40
  url: string;
11
41
  apiKey?: string | {
12
42
  header: string;
13
43
  value: string;
14
44
  };
15
- };
45
+ consumerId?: string;
46
+ jwtData?: RecordScannerJWTData;
47
+ viewKeys?: ViewKey[];
48
+ account?: Account;
49
+ cacheViewKeysOnRegister?: boolean;
50
+ autoReRegister?: boolean;
51
+ decryptEnabled?: boolean;
52
+ }
16
53
  /**
17
- * RecordScanner is a RecordProvider implementation that uses the record scanner service to find records.
54
+ * RecordScanner is a RecordProvider implementation that uses Provable's confidential record scanning service to find
55
+ * records.
18
56
  *
19
57
  * @example
20
58
  * const account = new Account({ privateKey: 'APrivateKey1...' });
21
59
  *
22
60
  * const recordScanner = new RecordScanner({ url: "https://record-scanner.aleo.org" });
23
61
  * recordScanner.setAccount(account);
24
- * recordScanner.setApiKey("your-api-key");
25
- * const uuid = await recordScanner.register(0);
62
+ * recordScanner.setApiKey("example-api-key");
63
+ * const result = await recordScanner.register(viewKey, 0);
64
+ * if (result.ok) { const uuid = result.data.uuid; }
26
65
  *
27
66
  * const filter = {
28
67
  * uuid,
@@ -55,76 +94,231 @@ type RecordScannerOptions = {
55
94
  * const records = await recordScanner.findRecords(filter);
56
95
  */
57
96
  declare class RecordScanner implements RecordProvider {
97
+ readonly cacheViewKeysOnRegister?: boolean;
58
98
  readonly url: string;
59
99
  private apiKey?;
100
+ private consumerId?;
101
+ private jwtData?;
60
102
  private uuid?;
103
+ private viewKeys?;
104
+ private autoReRegister?;
105
+ private decryptEnabled?;
106
+ account?: Account | undefined;
107
+ /**
108
+ * @param {RecordScannerOptions} options Configuration for the record scanner.
109
+ */
61
110
  constructor(options: RecordScannerOptions);
62
111
  /**
63
112
  * Set the API key to use for the record scanner.
64
113
  *
65
- * @param {string} apiKey The API key to use for the record scanner.
114
+ * @param {string | { header: string, value: string }} apiKey The API key to use for the record scanner.
66
115
  */
67
116
  setApiKey(apiKey: string | {
68
117
  header: string;
69
118
  value: string;
70
- }): Promise<void>;
119
+ }): void;
120
+ /**
121
+ * Set the consumer ID used for JWT refresh when using authenticated record scanner (e.g. Provable API).
122
+ *
123
+ * @param {string} consumerId The consumer ID to use for JWT refresh.
124
+ */
125
+ setConsumerId(consumerId: string): void;
126
+ /**
127
+ * Set JWT data for authentication. Optional; when not set, JWT can be refreshed from apiKey + consumerId if provided.
128
+ *
129
+ * @param {RecordScannerJWTData | undefined} jwtData The JWT data to use, or undefined to clear.
130
+ */
131
+ setJwtData(jwtData: RecordScannerJWTData | undefined): void;
132
+ /**
133
+ * Set whether /owned should automatically re-register on 422 (when a view key for the UUID is in viewKeys or account) and retry once.
134
+ *
135
+ * @param {boolean} enabled Whether to enable auto re-register on 422.
136
+ */
137
+ setAutoReRegister(enabled: boolean): void;
138
+ /**
139
+ * Set whether decryption of owned records is enabled (e.g. for use with the decrypt method).
140
+ *
141
+ * @param {boolean} enabled Whether to enable decryption of owned records received from the scanner using the `owned` or any `findRecords` methods.
142
+ */
143
+ setDecryptEnabled(enabled: boolean): void;
144
+ /**
145
+ * Add a view key to the record scanner for usage in local decryption. This is REQUIRED for findCreditsRecord/findCreditsRecords to work properly.
146
+ *
147
+ * @param {ViewKey} viewKey The view key to add.
148
+ */
149
+ addViewKey(viewKey: ViewKey): void;
150
+ /**
151
+ * Remove a view key from the record scanner.
152
+ *
153
+ * @param {string} uuid The uuid of the view key to remove.
154
+ */
155
+ removeViewKey(uuid: string): void;
156
+ /**
157
+ * Return the view key for the given record-scanner UUID if one is configured
158
+ * (in viewKeys or as the account's view key). Used to decide if re-registration on 422 is possible.
159
+ *
160
+ * @param {string} uuid The record-scanner UUID to look up.
161
+ * @returns {ViewKey | undefined} The view key for that UUID, or undefined.
162
+ */
163
+ private getViewKeyForUuid;
164
+ /**
165
+ * Set the primary account for the record scanner.
166
+ *
167
+ * @param {Account} account The account to set as the primary account.
168
+ */
169
+ setAccount(account: Account): void;
170
+ /**
171
+ * Refreshes the JWT by making a POST request to /jwts/{consumer_id}. Used when authentication is required.
172
+ *
173
+ * @param {string} apiKey The API key to use for the refresh request.
174
+ * @param {string} consumerId The consumer ID for the JWT endpoint.
175
+ * @returns {Promise<RecordScannerJWTData>} The new JWT data.
176
+ */
177
+ private refreshJwt;
178
+ /**
179
+ * Returns auth headers (e.g. Authorization with JWT). Refreshes JWT if expired and apiKey + consumerId are set. Empty when auth is not configured.
180
+ *
181
+ * @returns {Promise<Record<string, string>>} Auth headers to add to requests, or empty object when not configured.
182
+ */
183
+ private getAuthHeaders;
184
+ /**
185
+ * Set the UUID for the record scanner.
186
+ *
187
+ * @param {Field | ViewKey} keyMaterial The UUID to use for the record scanner. If a ViewKey is provided, the UUID will be computed from the key.
188
+ */
189
+ setUuid(keyMaterial: Field | ViewKey): void;
71
190
  /**
72
- * Set the UUID to use for the record scanner.
191
+ * If the error is a RecordScannerRequestError (from request()), return a RecordScannerFailure result;
192
+ * otherwise re-throw the error.
73
193
  *
74
- * @param {Field} uuid The UUID to use for the record scanner.
194
+ * @param {unknown} err The error from a failed request (e.g. from request() or from a catch after calling it).
195
+ * @returns {RecordScannerFailure} When err is RecordScannerRequestError.
196
+ * @throws Re-throws err when it is not a RecordScannerRequestError.
75
197
  */
76
- setUuid(uuidOrViewKey: Field | ViewKey): Promise<void>;
198
+ private handleRequestError;
77
199
  /**
78
- * Register the account with the record scanner service.
200
+ * Register the account with the record scanning service (unencrypted POST /register). Does not throw if a valid error response from the record scanner is received; returns a result object instead.
79
201
  *
202
+ * @param {ViewKey} viewKey The view key to register.
80
203
  * @param {number} startBlock The block height to start scanning from.
81
- * @returns {Promise<RegistrationResponse>} The response from the record scanner service.
204
+ * @returns {Promise<RegisterResult>} `{ ok: true, data }` on success, or `{ ok: false, status, error }` on failure.
82
205
  */
83
- register(viewKey: ViewKey, startBlock: number): Promise<RegistrationResponse>;
206
+ register(viewKey: ViewKey, startBlock: number): Promise<RegisterResult>;
84
207
  /**
85
- * Get encrypted records from the record scanner service.
208
+ * Fetches an ephemeral public key from the record scanning service for use with registerEncrypted.
209
+ * Follows the same pattern as the delegated proving service /pubkey endpoint.
210
+ *
211
+ * @returns {Promise<CryptoBoxPubKey>} The service's ephemeral public key and key_id.
212
+ */
213
+ getPubkey(): Promise<CryptoBoxPubKey>;
214
+ /**
215
+ * Registers the account with the record scanning service using the encrypted flow: 1. fetches an ephemeral public key from /pubkey - 2. encrypts the registration request (view key + start block) - 3. POSTs to /register/encrypted. Does not HTTP error on a proper error response from the record scanner; returns a result object instead.
216
+ *
217
+ * @param {ViewKey} viewKey The view key to register.
218
+ * @param {number} startBlock The block height to start scanning from.
219
+ * @returns {Promise<RegisterResult>} `{ ok: true, data }` on success, or `{ ok: false, status, error }` on failure.
220
+ */
221
+ registerEncrypted(viewKey: ViewKey, startBlock: number): Promise<RegisterResult>;
222
+ /**
223
+ * Remove all local scanner state associated with the given UUID (stored uuid, viewKeys entry, account if it matches).
224
+ * Called after a successful revoke so the scanner does not retain view keys or account for a revoked registration.
225
+ */
226
+ private clearLocalStateForUuid;
227
+ /**
228
+ * Revoke the account registration with the record scanning service (POST /revoke). On success, also removes
229
+ * all local state for that UUID: the stored UUID (if it matches), the view key for that UUID, and the
230
+ * account (if its view key corresponds to that UUID).
231
+ *
232
+ * @param {string | Field | undefined} uuid The UUID to revoke. If omitted, uses the UUID configured on the scanner.
233
+ * @returns {Promise<RevokeResult>} `{ ok: true, data: { status } }` on success, or `{ ok: false, status, error }` on failure.
234
+ * @throws {UUIDError} When no UUID is configured and none provided, or when the UUID string is invalid.
235
+ */
236
+ revoke(uuid?: string | Field): Promise<RevokeResult>;
237
+ /**
238
+ * Get encrypted records from the record scanning service. This is a safe variant of /records/encrypted that returns
239
+ * a result instead of throwing on HTTP error.
240
+ *
241
+ * @param {RecordsFilter} recordsFilter The filter to use to find the records and filter the response.
242
+ * @returns {Promise<EncryptedRecordsResult>} The encrypted records or an error if the request failed.
243
+ */
244
+ encrypted(recordsFilter: RecordsFilter): Promise<EncryptedRecordsResult>;
245
+ /**
246
+ * Get encrypted records from the record scanning service.
86
247
  *
87
248
  * @param {RecordsFilter} recordsFilter The filter to use to find the records and filter the response.
88
249
  * @returns {Promise<EncryptedRecord[]>} The encrypted records.
89
250
  */
90
251
  encryptedRecords(recordsFilter: RecordsFilter): Promise<EncryptedRecord[]>;
91
252
  /**
92
- * Check if a list of serial numbers exist in the record scanner service.
253
+ * Check if serial numbers appear in any record inputs on-chain, indicating that the records they belong to have been spent. This is a safe variant of /records/sns that returns a result instead of throwing on HTTP error.
254
+ *
255
+ * @param {string[]} serialNumbers The serial numbers to check.
256
+ * @returns {Promise<SerialNumbersResult>} Map of Aleo Record serial numbers and whether they appeared in any inputs on chain. If a boolean corresponding to the Serial Number has a true value, that Record is considered spent by the Aleo Network.
257
+ */
258
+ serialNumbers(serialNumbers: string[]): Promise<SerialNumbersResult>;
259
+ /**
260
+ * Check if serial numbers appear in any record inputs on-chain, indicating that the records they belong to have been spent.
93
261
  *
94
262
  * @param {string[]} serialNumbers The serial numbers to check.
95
263
  * @returns {Promise<Record<string, boolean>>} Map of Aleo Record serial numbers and whether they appeared in any inputs on chain. If boolean corresponding to the Serial Number has a true value, that Record is considered spent by the Aleo Network.
96
264
  */
97
265
  checkSerialNumbers(serialNumbers: string[]): Promise<Record<string, boolean>>;
98
266
  /**
99
- * Check if a list of tags exist in the record scanner service.
267
+ * Check if tags appear in any record inputs on-chain, indicating that the records they belong to have been spent. This is a safe variant of /records/tags that returns a result instead of throwing on HTTP error.
268
+ *
269
+ * *
270
+ * @param {string[]} tags The tags to check.
271
+ * @returns {Promise<TagsResult>} Map of Aleo Record tags and whether they appeared in any inputs on chain. If a boolean corresponding to the tag has a true value, that Record is considered spent by the Aleo Network.
272
+ */
273
+ tags(tags: string[]): Promise<TagsResult>;
274
+ /**
275
+ * Check if tags appear in any record inputs on-chain, indicating that the records they belong to have been spent.
100
276
  *
101
277
  * @param {string[]} tags The tags to check.
102
278
  * @returns {Promise<Record<string, boolean>>} Map of Aleo Record tags and whether they appeared in any inputs on chain. If boolean corresponding to the tag has a true value, that Record is considered spent by the Aleo Network.
103
279
  */
104
280
  checkTags(tags: string[]): Promise<Record<string, boolean>>;
105
281
  /**
106
- * Check the status of a record scanner indexing job.
282
+ * Check the scan completion job status for a specific UUID.
107
283
  *
108
- * @param {string} jobId The job id to check.
109
- * @returns {Promise<StatusResponse>} The status of the job.
284
+ * @param {string | Field | undefined} uuid The UUID of the job to check. If no UUID is provided as input, the UUID configured for the scanner will be used.
285
+ * @returns {Promise<StatusResult>} The status of the job or an error if the job could not be found.
110
286
  */
111
- checkStatus(): Promise<StatusResponse>;
287
+ status(uuid?: string | Field): Promise<StatusResult>;
112
288
  /**
113
- * Find a record in the record scanner service.
289
+ * Find a record in the record scanning service.
114
290
  *
115
291
  * @param {OwnedFilter} searchParameters The filter to use to find the record.
116
292
  * @returns {Promise<OwnedRecord>} The record.
117
293
  */
118
294
  findRecord(searchParameters: OwnedFilter): Promise<OwnedRecord>;
119
295
  /**
120
- * Find records in the record scanner service.
296
+ * Get owned records. Throws if the UUID passed in the OwnedFilter is invalid or is not configured in the record scanner otherwise returns the RESTFUL response from the record scanner.
297
+ *
298
+ * @param {OwnedFilter} filter The OwnedFilter used to specify the subset of owned records to select.
299
+ * @returns {Promise<OwnedRecordsResult>} Record belonging to the uuid passed in the filter or set on the Record Scanner.
300
+ */
301
+ owned(filter: OwnedFilter): Promise<OwnedRecordsResult>;
302
+ /**
303
+ * Find records using the record scanning service.
121
304
  *
122
- * @param {OwnedFilter} filter The filter to use to find the records.
305
+ * @param {OwnedFilter} searchParameters The filter to use to find the records.
123
306
  * @returns {Promise<OwnedRecord[]>} The records.
124
307
  */
125
- findRecords(filter: OwnedFilter): Promise<OwnedRecord[]>;
308
+ findRecords(searchParameters: OwnedFilter): Promise<OwnedRecord[]>;
309
+ /**
310
+ * Get RecordPlaintext from an OwnedRecord by parsing record_plaintext (trimmed). Returns null if missing or parse fails. Does not decrypt; decryption is handled only in owned().
311
+ */
312
+ private getPlaintext;
126
313
  /**
127
- * Find a credits record in the record scanner service.
314
+ * For each owned record provided, attempt to decrypt with the given view key. On success, sets record_plaintext on that record to the decrypted plaintext string. Records that fail to decrypt (e.g. wrong view key) or have no record_ciphertext are left unchanged.
315
+ *
316
+ * @param {ViewKey} viewKey The view key to use for decryption.
317
+ * @param {OwnedRecord[]} records The owned records to decrypt (mutated in place).
318
+ */
319
+ decrypt(viewKey: ViewKey, records: OwnedRecord[]): void;
320
+ /**
321
+ * Find a credits.aleo record in the record scanning service.
128
322
  *
129
323
  * @param {number} microcredits The amount of microcredits to find.
130
324
  * @param {OwnedFilter} searchParameters The filter to use to find the record.
@@ -132,7 +326,7 @@ declare class RecordScanner implements RecordProvider {
132
326
  */
133
327
  findCreditsRecord(microcredits: number, searchParameters: OwnedFilter): Promise<OwnedRecord>;
134
328
  /**
135
- * Find credits records using a record scanning service.
329
+ * Find credits records greater than or equal to the specified amounts using the record scanning service.
136
330
  *
137
331
  * @param {number[]} microcreditAmounts The amounts of microcredits to find.
138
332
  * @param {OwnedFilter} searchParameters The filter to use to find the records.
@@ -140,12 +334,34 @@ declare class RecordScanner implements RecordProvider {
140
334
  */
141
335
  findCreditsRecords(microcreditAmounts: number[], searchParameters: OwnedFilter): Promise<OwnedRecord[]>;
142
336
  /**
143
- * Wrapper function to make a request to the record scanner service and handle any errors.
337
+ * Wrapper function to make a request to the record scanning service and handle any errors. Optionally adds JWT Authorization header when consumerId/jwtData (or apiKey+consumerId) are configured.
144
338
  *
145
339
  * @param {Request} req The request to make.
146
- * @returns {Promise<Response>} The response.
340
+ * @returns {Promise<Response>} The response when the request succeeds.
341
+ * @throws {RecordScannerRequestError} When the server returns a non-2xx status (e.g. 4xx, 5xx).
342
+ * @throws Re-throws any error from fetch (e.g. network failure) or from getAuthHeaders().
147
343
  */
148
344
  private request;
149
- computeUUID(vk: ViewKey): Field;
345
+ /**
346
+ * Compute the record scanner UUID for a view key.
347
+ *
348
+ * @param {ViewKey} viewKey The view key to compute the UUID for.
349
+ * @returns {Field} The computed UUID corresponding to the view key.
350
+ */
351
+ computeUUID(viewKey: ViewKey): Field;
352
+ /**
353
+ * Validate a UUID string to ensure it represents a valid Aleo Record Scanner UUID.
354
+ *
355
+ * @param {string} uuid The UUID to validate.
356
+ * @returns {boolean} Whether the UUID is valid.
357
+ */
358
+ uuidIsValid(uuid: string): boolean;
359
+ /**
360
+ * Get the uuid for the filter, first by extracting the UUID from the filter, then falling back to the uuid configured within the record scanner.
361
+ *
362
+ * @param {OwnedFilter} filter The filter to extract the UUID from.
363
+ * @returns {string | undefined} The UUID for the filter, or undefined if the filter does not contain a UUID.
364
+ */
365
+ private getUUID;
150
366
  }
151
367
  export { RecordScanner };
@@ -0,0 +1,38 @@
1
+ import { ViewKey, Authorization, ProvingRequest } from "@provablehq/wasm";
2
+ /**
3
+ * Encrypt an authorization with a libsodium cryptobox public key.
4
+ *
5
+ * @param {string} publicKey The cryptobox X25519 public key to encrypt with (encoded in RFC 4648 standard Base64).
6
+ * @param {Authorization} authorization the authorization to encrypt.
7
+ *
8
+ * @returns {string} the encrypted authorization in RFC 4648 standard Base64.
9
+ */
10
+ export declare function encryptAuthorization(publicKey: string, authorization: Authorization): string;
11
+ /**
12
+ * Encrypt a ProvingRequest with a libsodium cryptobox public key.
13
+ *
14
+ * @param {string} publicKey The cryptobox X25519 public key to encrypt with (encoded in RFC 4648 standard Base64).
15
+ * @param {Authorization} provingRequest the ProvingRequest to encrypt.
16
+ *
17
+ * @returns {string} the encrypted ProvingRequest in RFC 4648 standard Base64.
18
+ */
19
+ export declare function encryptProvingRequest(publicKey: string, provingRequest: ProvingRequest): string;
20
+ /**
21
+ * Encrypt a view key with a libsodium cryptobox public key.
22
+ *
23
+ * @param {string} publicKey The cryptobox X25519 public key to encrypt with (encoded in RFC 4648 standard Base64).
24
+ * @param {ViewKey} viewKey the view key to encrypt.
25
+ *
26
+ * @returns {string} the encrypted view key in RFC 4648 standard Base64.
27
+ */
28
+ export declare function encryptViewKey(publicKey: string, viewKey: ViewKey): string;
29
+ /**
30
+ * Encrypt a record scanner registration request.
31
+ *
32
+ * @param {string} publicKey The cryptobox X25519 public key to encrypt with (encoded in RFC 4648 standard Base64).
33
+ * @param {ViewKey} viewKey the view key to encrypt.
34
+ * @param {number} start the start height of the registration request.
35
+ *
36
+ * @returns {string} the encrypted view key in RFC 4648 standard Base64.
37
+ */
38
+ export declare function encryptRegistrationRequest(publicKey: string, viewKey: ViewKey, start: number): string;
@@ -1,3 +1,4 @@
1
+ export declare function isNode(): boolean;
1
2
  export declare function environment(): "chrome" | "firefox" | "safari" | "edge" | "opera" | "browser" | "node" | "unknown";
2
3
  export declare function logAndThrow(message: string): never;
3
4
  export declare function parseJSON(json: string): any;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@provablehq/sdk",
3
- "version": "0.9.16-rc",
3
+ "version": "0.9.17",
4
4
  "description": "A Software Development Kit (SDK) for Zero-Knowledge Transactions",
5
5
  "collaborators": [
6
6
  "The Provable Team"
@@ -51,11 +51,12 @@
51
51
  },
52
52
  "homepage": "https://github.com/ProvableHQ/sdk#readme",
53
53
  "dependencies": {
54
- "@provablehq/wasm": "^0.9.16-rc",
54
+ "@provablehq/wasm": "^0.9.17",
55
55
  "@scure/base": "^2.0.0",
56
56
  "comlink": "^4.4.2",
57
57
  "core-js": "^3.40.0",
58
58
  "mime": "^4.0.6",
59
+ "libsodium-wrappers": "^0.8.2",
59
60
  "xmlhttprequest-ssl": "^4.0.0"
60
61
  },
61
62
  "devDependencies": {
@@ -78,7 +79,7 @@
78
79
  "mocha": "^11.1.0",
79
80
  "prettier": "3.4.2",
80
81
  "rimraf": "^6.0.1",
81
- "rollup": "^4.32.0",
82
+ "rollup": "^4.59.0",
82
83
  "rollup-plugin-typescript2": "^0.36.0",
83
84
  "sinon": "^19.0.2",
84
85
  "typescript": "^5.7.3"
@@ -1,81 +0,0 @@
1
- import { CachedKeyPair, FunctionKeyPair } from "../../models/keyPair.js";
2
- import { ProvingKey, VerifyingKey } from "../../wasm.js";
3
- export interface KeyStore {
4
- /**
5
- * Returns the proving and verifying keys for a given key locator from key storage.
6
- *
7
- * @param {string} locator The unique locator for the desired keypair.
8
- *
9
- * @returns {Promise<FunctionKeyPair | null>} Returns the proving and verifying keys for the given locator if they exist or null if they do not.
10
- */
11
- getKeys(locator: string): Promise<FunctionKeyPair | null>;
12
- /**
13
- * Returns the proving and verifying key as raw bytes for a given key locator from key storage.
14
- *
15
- * @param {string} locator The unique locator for the desired keypair.
16
- *
17
- * @returns {Promise<CachedKeyPair | null>} Returns the proving and verifying keys for the given locator as raw bytes if they exist or null if they do not. */
18
- getKeyBytes(locator: string): Promise<CachedKeyPair | null>;
19
- /**
20
- * Returns the `ProvingKey` for a given locator.
21
- *
22
- * @param {string} locator The unique locator for the desired `ProvingKey`.
23
- *
24
- * @returns {Promise<ProvingKey | null>} Returns the `ProvingKey` for the given locator if it exists or null if it does not.
25
- */
26
- getProvingKey(locator: string): Promise<ProvingKey | null>;
27
- /**
28
- * Returns the raw bytes of a `ProvingKey` for a given locator.
29
- *
30
- * @param {string} locator The unique locator for the desired `ProvingKey`.
31
- *
32
- * @returns {Promise<Uint8Array | null>} Returns the raw bytes of a `ProvingKey` for the given locator if it exists or null if it does not exist.
33
- */
34
- getProvingKeyBytes(locator: string): Promise<Uint8Array | null>;
35
- /**
36
- * Returns the `VerifyingKey` for a given locator.
37
- *
38
- * @param {string} locator The unique locator for the desired `VerifyingKey`.
39
- *
40
- * @returns {Promise<VerifyingKey | null>} Returns the `VerifyingKey` for the given locator if it exists or null if it does not exist.
41
- */
42
- getVerifyingKey(locator: string): Promise<VerifyingKey | null>;
43
- /**
44
- * Returns the raw bytes of a `VerifyingKey` for a given locator.
45
- *
46
- * @param {string} locator The unique locator for the desired `VerifyingKey`.
47
- *
48
- * @returns {Promise<Uint8Array | null>} Returns the raw bytes of a `VerifyingKey` for the given locator if it exists or null if it does not exist.
49
- */
50
- getVerifyingKeyBytes(locator: string): Promise<Uint8Array | null>;
51
- /**
52
- * Stores proving and verifying keys in key storage.
53
- *
54
- * @param {string} locator The unique locator for the desired keypair.
55
- * @param {FunctionKeyPair} keys The proving and verifying keys.
56
- */
57
- setKeys(locator: string, keys: FunctionKeyPair): Promise<void>;
58
- /**
59
- * Stores the raw proving and verifying key bytes in key storage.
60
- *
61
- * @param {string} locator The unique locator for the desired keypair.
62
- * @param {CachedKeyPair} keys The raw proving and verifying key bytes.
63
- */
64
- setKeyBytes(locator: string, keys: CachedKeyPair): Promise<void>;
65
- /**
66
- * Determines if a given keypair exists or not.
67
- *
68
- * @param {string} locator The unique locator for the desired keypair.
69
- */
70
- has(locator: string): Promise<boolean>;
71
- /**
72
- * Deletes a keypair corresponding to a given locator.
73
- *
74
- * @param {string} locator The unique locator for the desired keypair.
75
- */
76
- delete(locator: string): Promise<void>;
77
- /**
78
- * Clears all keys in the keystore.
79
- */
80
- clear(): Promise<void>;
81
- }
@@ -1,8 +0,0 @@
1
- import { CachedKeyPair } from "../../models/keyPair.js";
2
- import { KeyStore } from "./keystore.js";
3
- /**
4
- * @param {Map<string, CachedKeyPair>} map Any interface which returns a string as cached keypair bytes.
5
- *
6
- * @returns {KeyStore} The map decorated as a keystore.
7
- */
8
- export declare function promoteMapToKeyStore(map: Map<string, CachedKeyPair>): KeyStore;
@@ -1,81 +0,0 @@
1
- import { CachedKeyPair, FunctionKeyPair } from "../../models/keyPair.js";
2
- import { ProvingKey, VerifyingKey } from "../../wasm.js";
3
- export interface KeyStore {
4
- /**
5
- * Returns the proving and verifying keys for a given key locator from key storage.
6
- *
7
- * @param {string} locator The unique locator for the desired keypair.
8
- *
9
- * @returns {Promise<FunctionKeyPair | null>} Returns the proving and verifying keys for the given locator if they exist or null if they do not.
10
- */
11
- getKeys(locator: string): Promise<FunctionKeyPair | null>;
12
- /**
13
- * Returns the proving and verifying key as raw bytes for a given key locator from key storage.
14
- *
15
- * @param {string} locator The unique locator for the desired keypair.
16
- *
17
- * @returns {Promise<CachedKeyPair | null>} Returns the proving and verifying keys for the given locator as raw bytes if they exist or null if they do not. */
18
- getKeyBytes(locator: string): Promise<CachedKeyPair | null>;
19
- /**
20
- * Returns the `ProvingKey` for a given locator.
21
- *
22
- * @param {string} locator The unique locator for the desired `ProvingKey`.
23
- *
24
- * @returns {Promise<ProvingKey | null>} Returns the `ProvingKey` for the given locator if it exists or null if it does not.
25
- */
26
- getProvingKey(locator: string): Promise<ProvingKey | null>;
27
- /**
28
- * Returns the raw bytes of a `ProvingKey` for a given locator.
29
- *
30
- * @param {string} locator The unique locator for the desired `ProvingKey`.
31
- *
32
- * @returns {Promise<Uint8Array | null>} Returns the raw bytes of a `ProvingKey` for the given locator if it exists or null if it does not exist.
33
- */
34
- getProvingKeyBytes(locator: string): Promise<Uint8Array | null>;
35
- /**
36
- * Returns the `VerifyingKey` for a given locator.
37
- *
38
- * @param {string} locator The unique locator for the desired `VerifyingKey`.
39
- *
40
- * @returns {Promise<VerifyingKey | null>} Returns the `VerifyingKey` for the given locator if it exists or null if it does not exist.
41
- */
42
- getVerifyingKey(locator: string): Promise<VerifyingKey | null>;
43
- /**
44
- * Returns the raw bytes of a `VerifyingKey` for a given locator.
45
- *
46
- * @param {string} locator The unique locator for the desired `VerifyingKey`.
47
- *
48
- * @returns {Promise<Uint8Array | null>} Returns the raw bytes of a `VerifyingKey` for the given locator if it exists or null if it does not exist.
49
- */
50
- getVerifyingKeyBytes(locator: string): Promise<Uint8Array | null>;
51
- /**
52
- * Stores proving and verifying keys in key storage.
53
- *
54
- * @param {string} locator The unique locator for the desired keypair.
55
- * @param {FunctionKeyPair} keys The proving and verifying keys.
56
- */
57
- setKeys(locator: string, keys: FunctionKeyPair): Promise<void>;
58
- /**
59
- * Stores the raw proving and verifying key bytes in key storage.
60
- *
61
- * @param {string} locator The unique locator for the desired keypair.
62
- * @param {CachedKeyPair} keys The raw proving and verifying key bytes.
63
- */
64
- setKeyBytes(locator: string, keys: CachedKeyPair): Promise<void>;
65
- /**
66
- * Determines if a given keypair exists or not.
67
- *
68
- * @param {string} locator The unique locator for the desired keypair.
69
- */
70
- has(locator: string): Promise<boolean>;
71
- /**
72
- * Deletes a keypair corresponding to a given locator.
73
- *
74
- * @param {string} locator The unique locator for the desired keypair.
75
- */
76
- delete(locator: string): Promise<void>;
77
- /**
78
- * Clears all keys in the keystore.
79
- */
80
- clear(): Promise<void>;
81
- }
@@ -1,8 +0,0 @@
1
- import { CachedKeyPair } from "../../models/keyPair.js";
2
- import { KeyStore } from "./keystore.js";
3
- /**
4
- * @param {Map<string, CachedKeyPair>} map Any interface which returns a string as cached keypair bytes.
5
- *
6
- * @returns {KeyStore} The map decorated as a keystore.
7
- */
8
- export declare function promoteMapToKeyStore(map: Map<string, CachedKeyPair>): KeyStore;