@aztec/pxe 2.1.0-rc.9 → 3.0.0-devnet.2

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 (194) hide show
  1. package/README.md +5 -5
  2. package/dest/bin/check_oracle_version.js +18 -8
  3. package/dest/config/index.d.ts +8 -8
  4. package/dest/config/index.d.ts.map +1 -1
  5. package/dest/config/index.js +3 -3
  6. package/dest/config/package_info.js +1 -1
  7. package/dest/contract_function_simulator/contract_function_simulator.d.ts.map +1 -1
  8. package/dest/contract_function_simulator/contract_function_simulator.js +82 -26
  9. package/dest/contract_function_simulator/execution_data_provider.d.ts +27 -38
  10. package/dest/contract_function_simulator/execution_data_provider.d.ts.map +1 -1
  11. package/dest/contract_function_simulator/execution_note_cache.d.ts +2 -2
  12. package/dest/contract_function_simulator/execution_note_cache.d.ts.map +1 -1
  13. package/dest/contract_function_simulator/execution_note_cache.js +7 -4
  14. package/dest/contract_function_simulator/execution_tagging_index_cache.d.ts +16 -0
  15. package/dest/contract_function_simulator/execution_tagging_index_cache.d.ts.map +1 -0
  16. package/dest/contract_function_simulator/execution_tagging_index_cache.js +26 -0
  17. package/dest/contract_function_simulator/index.d.ts +3 -1
  18. package/dest/contract_function_simulator/index.d.ts.map +1 -1
  19. package/dest/contract_function_simulator/index.js +2 -1
  20. package/dest/contract_function_simulator/noir-structs/log_retrieval_response.d.ts.map +1 -1
  21. package/dest/contract_function_simulator/noir-structs/log_retrieval_response.js +7 -3
  22. package/dest/contract_function_simulator/noir-structs/note_validation_request.d.ts +1 -0
  23. package/dest/contract_function_simulator/noir-structs/note_validation_request.d.ts.map +1 -1
  24. package/dest/contract_function_simulator/noir-structs/note_validation_request.js +1 -1
  25. package/dest/contract_function_simulator/noir-structs/utility_context.d.ts +22 -0
  26. package/dest/contract_function_simulator/noir-structs/utility_context.d.ts.map +1 -0
  27. package/dest/contract_function_simulator/noir-structs/utility_context.js +33 -0
  28. package/dest/contract_function_simulator/oracle/index.d.ts +1 -1
  29. package/dest/contract_function_simulator/oracle/index.d.ts.map +1 -1
  30. package/dest/contract_function_simulator/oracle/index.js +1 -1
  31. package/dest/contract_function_simulator/oracle/interfaces.d.ts +97 -0
  32. package/dest/contract_function_simulator/oracle/interfaces.d.ts.map +1 -0
  33. package/dest/contract_function_simulator/oracle/interfaces.js +4 -0
  34. package/dest/contract_function_simulator/oracle/oracle.d.ts +12 -11
  35. package/dest/contract_function_simulator/oracle/oracle.d.ts.map +1 -1
  36. package/dest/contract_function_simulator/oracle/oracle.js +79 -76
  37. package/dest/contract_function_simulator/oracle/private_execution.d.ts +2 -2
  38. package/dest/contract_function_simulator/oracle/private_execution.d.ts.map +1 -1
  39. package/dest/contract_function_simulator/oracle/private_execution.js +6 -15
  40. package/dest/contract_function_simulator/oracle/private_execution_oracle.d.ts +26 -10
  41. package/dest/contract_function_simulator/oracle/private_execution_oracle.d.ts.map +1 -1
  42. package/dest/contract_function_simulator/oracle/private_execution_oracle.js +69 -18
  43. package/dest/contract_function_simulator/oracle/utility_execution_oracle.d.ts +10 -22
  44. package/dest/contract_function_simulator/oracle/utility_execution_oracle.d.ts.map +1 -1
  45. package/dest/contract_function_simulator/oracle/utility_execution_oracle.js +33 -38
  46. package/dest/contract_function_simulator/pxe_oracle_interface.d.ts +19 -55
  47. package/dest/contract_function_simulator/pxe_oracle_interface.d.ts.map +1 -1
  48. package/dest/contract_function_simulator/pxe_oracle_interface.js +174 -187
  49. package/dest/entrypoints/client/bundle/index.d.ts +3 -1
  50. package/dest/entrypoints/client/bundle/index.d.ts.map +1 -1
  51. package/dest/entrypoints/client/bundle/index.js +2 -1
  52. package/dest/entrypoints/client/bundle/utils.d.ts +8 -8
  53. package/dest/entrypoints/client/bundle/utils.d.ts.map +1 -1
  54. package/dest/entrypoints/client/bundle/utils.js +8 -8
  55. package/dest/entrypoints/client/lazy/index.d.ts +3 -1
  56. package/dest/entrypoints/client/lazy/index.d.ts.map +1 -1
  57. package/dest/entrypoints/client/lazy/index.js +2 -1
  58. package/dest/entrypoints/client/lazy/utils.d.ts +7 -7
  59. package/dest/entrypoints/client/lazy/utils.d.ts.map +1 -1
  60. package/dest/entrypoints/client/lazy/utils.js +7 -7
  61. package/dest/entrypoints/server/index.d.ts +3 -1
  62. package/dest/entrypoints/server/index.d.ts.map +1 -1
  63. package/dest/entrypoints/server/index.js +2 -1
  64. package/dest/entrypoints/server/utils.d.ts +4 -23
  65. package/dest/entrypoints/server/utils.d.ts.map +1 -1
  66. package/dest/entrypoints/server/utils.js +4 -25
  67. package/dest/{pxe_service/error_enriching.d.ts → error_enriching.d.ts} +1 -1
  68. package/dest/error_enriching.d.ts.map +1 -0
  69. package/dest/{pxe_service/error_enriching.js → error_enriching.js} +3 -0
  70. package/dest/oracle_version.d.ts +2 -2
  71. package/dest/oracle_version.js +2 -2
  72. package/dest/private_kernel/hints/compute_tx_include_by_timestamp.js +6 -6
  73. package/dest/private_kernel/private_kernel_execution_prover.d.ts +7 -0
  74. package/dest/private_kernel/private_kernel_execution_prover.d.ts.map +1 -1
  75. package/dest/private_kernel/private_kernel_execution_prover.js +23 -18
  76. package/dest/private_kernel/private_kernel_oracle_impl.d.ts +2 -2
  77. package/dest/pxe.d.ts +233 -0
  78. package/dest/pxe.d.ts.map +1 -0
  79. package/dest/{pxe_service/pxe_service.js → pxe.js} +215 -217
  80. package/dest/storage/address_data_provider/address_data_provider.d.ts +1 -3
  81. package/dest/storage/address_data_provider/address_data_provider.d.ts.map +1 -1
  82. package/dest/storage/address_data_provider/address_data_provider.js +0 -3
  83. package/dest/storage/capsule_data_provider/capsule_data_provider.d.ts +1 -3
  84. package/dest/storage/capsule_data_provider/capsule_data_provider.d.ts.map +1 -1
  85. package/dest/storage/capsule_data_provider/capsule_data_provider.js +0 -4
  86. package/dest/storage/contract_data_provider/contract_data_provider.d.ts +3 -4
  87. package/dest/storage/contract_data_provider/contract_data_provider.d.ts.map +1 -1
  88. package/dest/storage/contract_data_provider/contract_data_provider.js +0 -3
  89. package/dest/storage/index.d.ts +0 -1
  90. package/dest/storage/index.d.ts.map +1 -1
  91. package/dest/storage/index.js +0 -1
  92. package/dest/storage/note_data_provider/note_dao.d.ts +1 -1
  93. package/dest/storage/note_data_provider/note_dao.d.ts.map +1 -1
  94. package/dest/storage/note_data_provider/note_data_provider.d.ts +70 -7
  95. package/dest/storage/note_data_provider/note_data_provider.d.ts.map +1 -1
  96. package/dest/storage/note_data_provider/note_data_provider.js +120 -72
  97. package/dest/storage/private_event_data_provider/private_event_data_provider.d.ts +1 -3
  98. package/dest/storage/private_event_data_provider/private_event_data_provider.d.ts.map +1 -1
  99. package/dest/storage/private_event_data_provider/private_event_data_provider.js +0 -3
  100. package/dest/storage/sync_data_provider/sync_data_provider.d.ts +1 -3
  101. package/dest/storage/sync_data_provider/sync_data_provider.d.ts.map +1 -1
  102. package/dest/storage/sync_data_provider/sync_data_provider.js +0 -3
  103. package/dest/storage/tagging_data_provider/tagging_data_provider.d.ts +28 -6
  104. package/dest/storage/tagging_data_provider/tagging_data_provider.d.ts.map +1 -1
  105. package/dest/storage/tagging_data_provider/tagging_data_provider.js +46 -39
  106. package/dest/synchronizer/synchronizer.d.ts.map +1 -1
  107. package/dest/synchronizer/synchronizer.js +2 -3
  108. package/dest/tagging/constants.d.ts +2 -0
  109. package/dest/tagging/constants.d.ts.map +1 -0
  110. package/dest/tagging/constants.js +2 -0
  111. package/dest/tagging/index.d.ts +7 -0
  112. package/dest/tagging/index.d.ts.map +1 -0
  113. package/dest/tagging/index.js +5 -0
  114. package/dest/tagging/siloed_tag.d.ts +14 -0
  115. package/dest/tagging/siloed_tag.d.ts.map +1 -0
  116. package/dest/tagging/siloed_tag.js +20 -0
  117. package/dest/tagging/tag.d.ts +12 -0
  118. package/dest/tagging/tag.d.ts.map +1 -0
  119. package/dest/tagging/tag.js +17 -0
  120. package/dest/tagging/utils.d.ts +18 -0
  121. package/dest/tagging/utils.d.ts.map +1 -0
  122. package/dest/tagging/utils.js +24 -0
  123. package/package.json +18 -21
  124. package/src/bin/check_oracle_version.ts +23 -9
  125. package/src/config/index.ts +11 -10
  126. package/src/config/package_info.ts +1 -1
  127. package/src/contract_function_simulator/contract_function_simulator.ts +128 -44
  128. package/src/contract_function_simulator/execution_data_provider.ts +29 -47
  129. package/src/contract_function_simulator/execution_note_cache.ts +11 -6
  130. package/src/contract_function_simulator/execution_tagging_index_cache.ts +32 -0
  131. package/src/contract_function_simulator/index.ts +3 -1
  132. package/src/contract_function_simulator/noir-structs/log_retrieval_response.ts +8 -3
  133. package/src/contract_function_simulator/noir-structs/note_validation_request.ts +1 -1
  134. package/src/contract_function_simulator/noir-structs/utility_context.ts +42 -0
  135. package/src/contract_function_simulator/oracle/index.ts +1 -1
  136. package/src/contract_function_simulator/oracle/interfaces.ts +160 -0
  137. package/src/contract_function_simulator/oracle/oracle.ts +102 -77
  138. package/src/contract_function_simulator/oracle/private_execution.ts +7 -15
  139. package/src/contract_function_simulator/oracle/private_execution_oracle.ts +106 -45
  140. package/src/contract_function_simulator/oracle/utility_execution_oracle.ts +51 -76
  141. package/src/contract_function_simulator/pxe_oracle_interface.ts +199 -218
  142. package/src/entrypoints/client/bundle/index.ts +3 -1
  143. package/src/entrypoints/client/bundle/utils.ts +11 -19
  144. package/src/entrypoints/client/lazy/index.ts +3 -1
  145. package/src/entrypoints/client/lazy/utils.ts +10 -18
  146. package/src/entrypoints/server/index.ts +3 -1
  147. package/src/entrypoints/server/utils.ts +9 -39
  148. package/src/{pxe_service/error_enriching.ts → error_enriching.ts} +5 -1
  149. package/src/oracle_version.ts +2 -2
  150. package/src/private_kernel/hints/compute_tx_include_by_timestamp.ts +6 -6
  151. package/src/private_kernel/private_kernel_execution_prover.ts +35 -23
  152. package/src/{pxe_service/pxe_service.ts → pxe.ts} +230 -261
  153. package/src/storage/address_data_provider/address_data_provider.ts +1 -7
  154. package/src/storage/capsule_data_provider/capsule_data_provider.ts +1 -11
  155. package/src/storage/contract_data_provider/contract_data_provider.ts +3 -9
  156. package/src/storage/index.ts +0 -1
  157. package/src/storage/note_data_provider/note_dao.ts +1 -1
  158. package/src/storage/note_data_provider/note_data_provider.ts +142 -99
  159. package/src/storage/private_event_data_provider/private_event_data_provider.ts +1 -7
  160. package/src/storage/sync_data_provider/sync_data_provider.ts +1 -7
  161. package/src/storage/tagging_data_provider/tagging_data_provider.ts +52 -55
  162. package/src/synchronizer/synchronizer.ts +2 -3
  163. package/src/tagging/constants.ts +2 -0
  164. package/src/tagging/index.ts +6 -0
  165. package/src/tagging/siloed_tag.ts +22 -0
  166. package/src/tagging/tag.ts +16 -0
  167. package/src/tagging/utils.ts +31 -0
  168. package/dest/bin/index.d.ts +0 -3
  169. package/dest/bin/index.d.ts.map +0 -1
  170. package/dest/bin/index.js +0 -48
  171. package/dest/contract_function_simulator/oracle/typed_oracle.d.ts +0 -87
  172. package/dest/contract_function_simulator/oracle/typed_oracle.d.ts.map +0 -1
  173. package/dest/contract_function_simulator/oracle/typed_oracle.js +0 -146
  174. package/dest/contract_function_simulator/tagging_utils.d.ts +0 -17
  175. package/dest/contract_function_simulator/tagging_utils.d.ts.map +0 -1
  176. package/dest/contract_function_simulator/tagging_utils.js +0 -23
  177. package/dest/pxe_service/error_enriching.d.ts.map +0 -1
  178. package/dest/pxe_service/index.d.ts +0 -3
  179. package/dest/pxe_service/index.d.ts.map +0 -1
  180. package/dest/pxe_service/index.js +0 -2
  181. package/dest/pxe_service/pxe_service.d.ts +0 -101
  182. package/dest/pxe_service/pxe_service.d.ts.map +0 -1
  183. package/dest/storage/data_provider.d.ts +0 -4
  184. package/dest/storage/data_provider.d.ts.map +0 -1
  185. package/dest/storage/data_provider.js +0 -1
  186. package/dest/test/pxe_test_suite.d.ts +0 -3
  187. package/dest/test/pxe_test_suite.d.ts.map +0 -1
  188. package/dest/test/pxe_test_suite.js +0 -97
  189. package/src/bin/index.ts +0 -62
  190. package/src/contract_function_simulator/oracle/typed_oracle.ts +0 -289
  191. package/src/contract_function_simulator/tagging_utils.ts +0 -32
  192. package/src/pxe_service/index.ts +0 -2
  193. package/src/storage/data_provider.ts +0 -3
  194. package/src/test/pxe_test_suite.ts +0 -113
@@ -3,9 +3,7 @@ import type { AztecAsyncArray, AztecAsyncKVStore, AztecAsyncMap } from '@aztec/k
3
3
  import type { AztecAddress } from '@aztec/stdlib/aztec-address';
4
4
  import { CompleteAddress } from '@aztec/stdlib/contract';
5
5
 
6
- import type { DataProvider } from '../data_provider.js';
7
-
8
- export class AddressDataProvider implements DataProvider {
6
+ export class AddressDataProvider {
9
7
  #store: AztecAsyncKVStore;
10
8
  #completeAddresses: AztecAsyncArray<Buffer>;
11
9
  #completeAddressIndex: AztecAsyncMap<string, number>;
@@ -64,8 +62,4 @@ export class AddressDataProvider implements DataProvider {
64
62
  (await toArray(this.#completeAddresses.valuesAsync())).map(v => CompleteAddress.fromBuffer(v)),
65
63
  );
66
64
  }
67
-
68
- async getSize(): Promise<number> {
69
- return (await this.#completeAddresses.lengthAsync()) * CompleteAddress.SIZE_IN_BYTES;
70
- }
71
65
  }
@@ -1,12 +1,9 @@
1
1
  import { Fr } from '@aztec/foundation/fields';
2
- import { toArray } from '@aztec/foundation/iterable';
3
2
  import { type Logger, createLogger } from '@aztec/foundation/log';
4
3
  import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
5
4
  import type { AztecAddress } from '@aztec/stdlib/aztec-address';
6
5
 
7
- import type { DataProvider } from '../data_provider.js';
8
-
9
- export class CapsuleDataProvider implements DataProvider {
6
+ export class CapsuleDataProvider {
10
7
  #store: AztecAsyncKVStore;
11
8
 
12
9
  // Arbitrary data stored by contracts. Key is computed as `${contractAddress}:${key}`
@@ -139,13 +136,6 @@ export class CapsuleDataProvider implements DataProvider {
139
136
  }
140
137
  });
141
138
  }
142
-
143
- public async getSize() {
144
- return (await toArray(this.#capsules.valuesAsync())).reduce(
145
- (sum, value) => sum + value.length * Fr.SIZE_IN_BYTES,
146
- 0,
147
- );
148
- }
149
139
  }
150
140
 
151
141
  function dbSlotToKey(contractAddress: AztecAddress, slot: Fr): string {
@@ -1,3 +1,4 @@
1
+ import type { FUNCTION_TREE_HEIGHT } from '@aztec/constants';
1
2
  import type { Fr } from '@aztec/foundation/fields';
2
3
  import { toArray } from '@aztec/foundation/iterable';
3
4
  import type { MembershipWitness } from '@aztec/foundation/trees';
@@ -22,7 +23,6 @@ import {
22
23
  getContractClassFromArtifact,
23
24
  } from '@aztec/stdlib/contract';
24
25
 
25
- import type { DataProvider } from '../data_provider.js';
26
26
  import { PrivateFunctionsTree } from './private_functions_tree.js';
27
27
 
28
28
  /**
@@ -32,7 +32,7 @@ import { PrivateFunctionsTree } from './private_functions_tree.js';
32
32
  * to efficiently serve the requested data. It interacts with the ContractDatabase and AztecNode to fetch
33
33
  * the required information and facilitate cryptographic proof generation.
34
34
  */
35
- export class ContractDataProvider implements DataProvider {
35
+ export class ContractDataProvider {
36
36
  /** Map from contract class id to private function tree. */
37
37
  // TODO: Update it to be LRU cache so that it doesn't keep all the data all the time.
38
38
  #privateFunctionTrees: Map<string, PrivateFunctionsTree> = new Map();
@@ -248,7 +248,7 @@ export class ContractDataProvider implements DataProvider {
248
248
  public async getFunctionMembershipWitness(
249
249
  contractClassId: Fr,
250
250
  selector: FunctionSelector,
251
- ): Promise<MembershipWitness<5> | undefined> {
251
+ ): Promise<MembershipWitness<typeof FUNCTION_TREE_HEIGHT> | undefined> {
252
252
  const tree = await this.#getPrivateFunctionTreeForClassId(contractClassId);
253
253
  return tree?.getFunctionMembershipWitness(selector);
254
254
  }
@@ -264,12 +264,6 @@ export class ContractDataProvider implements DataProvider {
264
264
  return `${artifact?.name ?? contractAddress}:${fnArtifact?.name ?? selector}`;
265
265
  }
266
266
 
267
- public async getSize() {
268
- return (await toArray(this.#contractInstances.valuesAsync()))
269
- .concat(await toArray(this.#contractArtifacts.valuesAsync()))
270
- .reduce((sum, value) => sum + value.length, 0);
271
- }
272
-
273
267
  async #findFunctionArtifactBySelector(
274
268
  artifact: ContractArtifact,
275
269
  selector: FunctionSelector,
@@ -4,6 +4,5 @@ export * from './contract_data_provider/index.js';
4
4
  export * from './note_data_provider/index.js';
5
5
  export * from './sync_data_provider/index.js';
6
6
  export * from './tagging_data_provider/index.js';
7
- export * from './data_provider.js';
8
7
  export * from './metadata.js';
9
8
  export * from './private_event_data_provider/private_event_data_provider.js';
@@ -5,7 +5,7 @@ import { AztecAddress } from '@aztec/stdlib/aztec-address';
5
5
  import { Note } from '@aztec/stdlib/note';
6
6
  import { TxHash } from '@aztec/stdlib/tx';
7
7
 
8
- import type { NoteData } from '../../contract_function_simulator/oracle/typed_oracle.js';
8
+ import type { NoteData } from '../../contract_function_simulator/oracle/interfaces.js';
9
9
 
10
10
  /**
11
11
  * A Note Data Access Object, representing a note that was committed to the note hash tree, holding all of the
@@ -6,12 +6,16 @@ import { AztecAddress } from '@aztec/stdlib/aztec-address';
6
6
  import type { InBlock } from '@aztec/stdlib/block';
7
7
  import { NoteStatus, type NotesFilter } from '@aztec/stdlib/note';
8
8
 
9
- import type { DataProvider } from '../data_provider.js';
10
9
  import { NoteDao } from './note_dao.js';
11
10
 
12
- export class NoteDataProvider implements DataProvider {
11
+ /**
12
+ * NoteDataProvider manages the storage and retrieval of notes.
13
+ *
14
+ * Notes can be active or nullified. This class processes new notes, nullifications,
15
+ * and performs rollback handling in the case of a reorg.
16
+ **/
17
+ export class NoteDataProvider {
13
18
  #store: AztecAsyncKVStore;
14
-
15
19
  #notes: AztecAsyncMap<string, Buffer>;
16
20
  #nullifiedNotes: AztecAsyncMap<string, Buffer>;
17
21
  #nullifierToNoteId: AztecAsyncMap<string, string>;
@@ -20,16 +24,12 @@ export class NoteDataProvider implements DataProvider {
20
24
  #nullifiedNotesToScope: AztecAsyncMultiMap<string, string>;
21
25
  #nullifiedNotesByContract: AztecAsyncMultiMap<string, string>;
22
26
  #nullifiedNotesByStorageSlot: AztecAsyncMultiMap<string, string>;
23
- #nullifiedNotesByTxHash: AztecAsyncMultiMap<string, string>;
24
- #nullifiedNotesByRecipient: AztecAsyncMultiMap<string, string>;
25
27
  #nullifiedNotesByNullifier: AztecAsyncMap<string, string>;
26
28
 
27
29
  #scopes: AztecAsyncMap<string, true>;
28
30
  #notesToScope: AztecAsyncMultiMap<string, string>;
29
31
  #notesByContractAndScope: Map<string, AztecAsyncMultiMap<string, string>>;
30
32
  #notesByStorageSlotAndScope: Map<string, AztecAsyncMultiMap<string, string>>;
31
- #notesByTxHashAndScope: Map<string, AztecAsyncMultiMap<string, string>>;
32
- #notesByRecipientAndScope: Map<string, AztecAsyncMultiMap<string, string>>;
33
33
 
34
34
  private constructor(store: AztecAsyncKVStore) {
35
35
  this.#store = store;
@@ -41,29 +41,41 @@ export class NoteDataProvider implements DataProvider {
41
41
  this.#nullifiedNotesToScope = store.openMultiMap('nullified_notes_to_scope');
42
42
  this.#nullifiedNotesByContract = store.openMultiMap('nullified_notes_by_contract');
43
43
  this.#nullifiedNotesByStorageSlot = store.openMultiMap('nullified_notes_by_storage_slot');
44
- this.#nullifiedNotesByTxHash = store.openMultiMap('nullified_notes_by_tx_hash');
45
- this.#nullifiedNotesByRecipient = store.openMultiMap('nullified_notes_by_recipient');
46
44
  this.#nullifiedNotesByNullifier = store.openMap('nullified_notes_by_nullifier');
47
45
 
48
46
  this.#scopes = store.openMap('scopes');
49
47
  this.#notesToScope = store.openMultiMap('notes_to_scope');
50
48
  this.#notesByContractAndScope = new Map<string, AztecAsyncMultiMap<string, string>>();
51
49
  this.#notesByStorageSlotAndScope = new Map<string, AztecAsyncMultiMap<string, string>>();
52
- this.#notesByTxHashAndScope = new Map<string, AztecAsyncMultiMap<string, string>>();
53
- this.#notesByRecipientAndScope = new Map<string, AztecAsyncMultiMap<string, string>>();
54
50
  }
55
51
 
52
+ /**
53
+ * Creates and initializes a new NoteDataProvider instance.
54
+ *
55
+ * This factory method creates a NoteDataProvider and restores any existing
56
+ * scope-specific indexes from the database.
57
+ *
58
+ * @param store - The key-value store to use for persistence
59
+ * @returns Promise resolving to a fully initialized NoteDataProvider instance
60
+ */
56
61
  public static async create(store: AztecAsyncKVStore): Promise<NoteDataProvider> {
57
62
  const pxeDB = new NoteDataProvider(store);
58
63
  for await (const scope of pxeDB.#scopes.keysAsync()) {
59
64
  pxeDB.#notesByContractAndScope.set(scope, store.openMultiMap(`${scope}:notes_by_contract`));
60
65
  pxeDB.#notesByStorageSlotAndScope.set(scope, store.openMultiMap(`${scope}:notes_by_storage_slot`));
61
- pxeDB.#notesByTxHashAndScope.set(scope, store.openMultiMap(`${scope}:notes_by_tx_hash`));
62
- pxeDB.#notesByRecipientAndScope.set(scope, store.openMultiMap(`${scope}:notes_by_recipient`));
63
66
  }
64
67
  return pxeDB;
65
68
  }
66
69
 
70
+ /**
71
+ * Adds a new scope to the note data provider.
72
+ *
73
+ * Scopes provide privacy isolation by creating separate indexes for each user.
74
+ * Each scope gets its own set of indexes for efficient note retrieval by various criteria.
75
+ *
76
+ * @param scope - The AztecAddress representing the scope/user to add
77
+ * @returns Promise resolving to true if scope was added, false if it already existed
78
+ */
67
79
  public async addScope(scope: AztecAddress): Promise<boolean> {
68
80
  const scopeString = scope.toString();
69
81
 
@@ -74,23 +86,27 @@ export class NoteDataProvider implements DataProvider {
74
86
  await this.#scopes.set(scopeString, true);
75
87
  this.#notesByContractAndScope.set(scopeString, this.#store.openMultiMap(`${scopeString}:notes_by_contract`));
76
88
  this.#notesByStorageSlotAndScope.set(scopeString, this.#store.openMultiMap(`${scopeString}:notes_by_storage_slot`));
77
- this.#notesByTxHashAndScope.set(scopeString, this.#store.openMultiMap(`${scopeString}:notes_by_tx_hash`));
78
- this.#notesByRecipientAndScope.set(scopeString, this.#store.openMultiMap(`${scopeString}:notes_by_recipient`));
79
89
 
80
90
  return true;
81
91
  }
82
92
 
83
- addNotes(notes: NoteDao[], scope: AztecAddress = AztecAddress.ZERO): Promise<void> {
93
+ /**
94
+ * Adds multiple notes to the data provider under the specified scope.
95
+ *
96
+ * Notes are stored using their index from the notes hash tree as the key, which provides
97
+ * uniqueness and maintains creation order. Each note is indexed by multiple criteria
98
+ * for efficient retrieval.
99
+ *
100
+ * @param notes - Notes to store
101
+ * @param scope - The scope (user/account) under which to store the notes
102
+ */
103
+ addNotes(notes: NoteDao[], scope: AztecAddress): Promise<void> {
84
104
  return this.#store.transactionAsync(async () => {
85
105
  if (!(await this.#scopes.hasAsync(scope.toString()))) {
86
106
  await this.addScope(scope);
87
107
  }
88
108
 
89
109
  for (const dao of notes) {
90
- // store notes by their index in the notes hash tree
91
- // this provides the uniqueness we need to store individual notes
92
- // and should also return notes in the order that they were created.
93
- // Had we stored them by their nullifier, they would be returned in random order
94
110
  const noteIndex = toBufferBE(dao.index, 32).toString('hex');
95
111
  await this.#notes.set(noteIndex, dao.toBuffer());
96
112
  await this.#notesToScope.set(noteIndex, scope.toString());
@@ -98,13 +114,34 @@ export class NoteDataProvider implements DataProvider {
98
114
 
99
115
  await this.#notesByContractAndScope.get(scope.toString())!.set(dao.contractAddress.toString(), noteIndex);
100
116
  await this.#notesByStorageSlotAndScope.get(scope.toString())!.set(dao.storageSlot.toString(), noteIndex);
101
- await this.#notesByTxHashAndScope.get(scope.toString())!.set(dao.txHash.toString(), noteIndex);
102
- await this.#notesByRecipientAndScope.get(scope.toString())!.set(dao.recipient.toString(), noteIndex);
103
117
  }
104
118
  });
105
119
  }
106
120
 
107
- public removeNotesAfter(blockNumber: number): Promise<void> {
121
+ /**
122
+ * Synchronizes notes and nullifiers to a specific block number.
123
+ *
124
+ * This method ensures that the state of notes and nullifiers is consistent with the
125
+ * specified block number. It restores any notes that were nullified after the given block
126
+ * and deletes any active notes created after that block.
127
+ *
128
+ * @param blockNumber - The new chain tip after a reorg
129
+ * @param synchedBlockNumber - The block number up to which PXE managed to sync before the reorg happened.
130
+ */
131
+ public async rollbackNotesAndNullifiers(blockNumber: number, synchedBlockNumber: number): Promise<void> {
132
+ await this.#rewindNullifiersAfterBlock(blockNumber, synchedBlockNumber);
133
+ await this.#deleteActiveNotesAfterBlock(blockNumber);
134
+ }
135
+
136
+ /**
137
+ * Deletes (removes) all active notes created after the specified block number.
138
+ *
139
+ * Permanently delete notes from the active notes store, e.g. during a reorg.
140
+ * Note: This only affects #notes (active notes), not #nullifiedNotes.
141
+ *
142
+ * @param blockNumber - Notes created after this block number will be deleted
143
+ */
144
+ #deleteActiveNotesAfterBlock(blockNumber: number): Promise<void> {
108
145
  return this.#store.transactionAsync(async () => {
109
146
  const notes = await toArray(this.#notes.valuesAsync());
110
147
  for (const note of notes) {
@@ -116,8 +153,6 @@ export class NoteDataProvider implements DataProvider {
116
153
  await this.#nullifierToNoteId.delete(noteDao.siloedNullifier.toString());
117
154
  const scopes = await toArray(this.#scopes.keysAsync());
118
155
  for (const scope of scopes) {
119
- await this.#notesByRecipientAndScope.get(scope)!.deleteValue(noteDao.recipient.toString(), noteIndex);
120
- await this.#notesByTxHashAndScope.get(scope)!.deleteValue(noteDao.txHash.toString(), noteIndex);
121
156
  await this.#notesByContractAndScope.get(scope)!.deleteValue(noteDao.contractAddress.toString(), noteIndex);
122
157
  await this.#notesByStorageSlotAndScope.get(scope)!.deleteValue(noteDao.storageSlot.toString(), noteIndex);
123
158
  }
@@ -126,12 +161,21 @@ export class NoteDataProvider implements DataProvider {
126
161
  });
127
162
  }
128
163
 
129
- public async unnullifyNotesAfter(blockNumber: number, synchedBlockNumber?: number): Promise<void> {
164
+ /**
165
+ * Rewinds nullifications after a given block number.
166
+ *
167
+ * This operation "unnullifies" notes, rolling back nullifications that occurred
168
+ * in orphaned blocks, e.g. during a reorg. The notes are restored to the
169
+ * active notes store and removed from the nullified store.
170
+ *
171
+ * @param blockNumber - Revert nullifications that occurred after this block
172
+ * @param synchedBlockNumber - Upper bound for the block range to process
173
+ */
174
+ async #rewindNullifiersAfterBlock(blockNumber: number, synchedBlockNumber: number): Promise<void> {
130
175
  await this.#store.transactionAsync(async () => {
131
176
  const nullifiersToUndo: string[] = [];
132
177
  const currentBlockNumber = blockNumber + 1;
133
- const maxBlockNumber = synchedBlockNumber ?? currentBlockNumber;
134
- for (let i = currentBlockNumber; i <= maxBlockNumber; i++) {
178
+ for (let i = currentBlockNumber; i <= synchedBlockNumber; i++) {
135
179
  nullifiersToUndo.push(...(await toArray(this.#nullifiersByBlockNumber.getValuesAsync(i))));
136
180
  }
137
181
  const notesIndexesToReinsert = await Promise.all(
@@ -159,8 +203,6 @@ export class NoteDataProvider implements DataProvider {
159
203
  for (const scope of scopes) {
160
204
  await this.#notesByContractAndScope.get(scope.toString())!.set(dao.contractAddress.toString(), noteIndex);
161
205
  await this.#notesByStorageSlotAndScope.get(scope.toString())!.set(dao.storageSlot.toString(), noteIndex);
162
- await this.#notesByTxHashAndScope.get(scope.toString())!.set(dao.txHash.toString(), noteIndex);
163
- await this.#notesByRecipientAndScope.get(scope.toString())!.set(dao.recipient.toString(), noteIndex);
164
206
  await this.#notesToScope.set(noteIndex, scope);
165
207
  }
166
208
 
@@ -169,16 +211,32 @@ export class NoteDataProvider implements DataProvider {
169
211
  await this.#nullifiersByBlockNumber.deleteValue(dao.l2BlockNumber, dao.siloedNullifier.toString());
170
212
  await this.#nullifiedNotesByContract.deleteValue(dao.contractAddress.toString(), noteIndex);
171
213
  await this.#nullifiedNotesByStorageSlot.deleteValue(dao.storageSlot.toString(), noteIndex);
172
- await this.#nullifiedNotesByTxHash.deleteValue(dao.txHash.toString(), noteIndex);
173
- await this.#nullifiedNotesByRecipient.deleteValue(dao.recipient.toString(), noteIndex);
174
214
  await this.#nullifiedNotesByNullifier.delete(dao.siloedNullifier.toString());
175
215
  }
176
216
  });
177
217
  }
178
218
 
219
+ /**
220
+ * Retrieves notes based on the provided filter criteria.
221
+ *
222
+ * This method queries both active and optionally nullified notes based on the filter
223
+ * parameters.
224
+ *
225
+ * @param filter - Filter criteria including contractAddress (required), and optional
226
+ * storageSlot, status, scopes and siloedNullifier.
227
+ * @returns Promise resolving to array of NoteDao objects matching the filter
228
+ * @throws If filtering by an empty scopes array. Scopes have to be set to undefined or to a non-empty array.
229
+ */
179
230
  async getNotes(filter: NotesFilter): Promise<NoteDao[]> {
180
231
  filter.status = filter.status ?? NoteStatus.ACTIVE;
181
232
 
233
+ // throw early if scopes is an empty array
234
+ if (filter.scopes !== undefined && filter.scopes.length === 0) {
235
+ throw new Error(
236
+ 'Trying to get notes with an empty scopes array. Scopes have to be set to undefined if intending on not filtering by scopes.',
237
+ );
238
+ }
239
+
182
240
  const candidateNoteSources = [];
183
241
 
184
242
  filter.scopes ??= (await toArray(this.#scopes.keysAsync())).map(addressString =>
@@ -190,29 +248,19 @@ export class NoteDataProvider implements DataProvider {
190
248
  for (const scope of new Set(filter.scopes)) {
191
249
  const formattedScopeString = scope.toString();
192
250
  if (!(await this.#scopes.hasAsync(formattedScopeString))) {
193
- throw new Error('Trying to get incoming notes of an scope that is not in the PXE database');
251
+ throw new Error('Trying to get incoming notes of a scope that is not in the PXE database');
194
252
  }
195
253
 
196
254
  activeNoteIdsPerScope.push(
197
- filter.recipient
255
+ filter.storageSlot
198
256
  ? await toArray(
199
- this.#notesByRecipientAndScope.get(formattedScopeString)!.getValuesAsync(filter.recipient.toString()),
257
+ this.#notesByStorageSlotAndScope.get(formattedScopeString)!.getValuesAsync(filter.storageSlot.toString()),
200
258
  )
201
- : filter.txHash
202
- ? await toArray(
203
- this.#notesByTxHashAndScope.get(formattedScopeString)!.getValuesAsync(filter.txHash.toString()),
204
- )
205
- : filter.storageSlot
206
- ? await toArray(
207
- this.#notesByStorageSlotAndScope
208
- .get(formattedScopeString)!
209
- .getValuesAsync(filter.storageSlot.toString()),
210
- )
211
- : await toArray(
212
- this.#notesByContractAndScope
213
- .get(formattedScopeString)!
214
- .getValuesAsync(filter.contractAddress.toString()),
215
- ),
259
+ : await toArray(
260
+ this.#notesByContractAndScope
261
+ .get(formattedScopeString)!
262
+ .getValuesAsync(filter.contractAddress.toString()),
263
+ ),
216
264
  );
217
265
  }
218
266
 
@@ -221,17 +269,28 @@ export class NoteDataProvider implements DataProvider {
221
269
  notes: this.#notes,
222
270
  });
223
271
 
224
- if (filter.status == NoteStatus.ACTIVE_OR_NULLIFIED) {
225
- candidateNoteSources.push({
226
- ids: filter.recipient
227
- ? await toArray(this.#nullifiedNotesByRecipient.getValuesAsync(filter.recipient.toString()))
228
- : filter.txHash
229
- ? await toArray(this.#nullifiedNotesByTxHash.getValuesAsync(filter.txHash.toString()))
230
- : filter.storageSlot
231
- ? await toArray(this.#nullifiedNotesByStorageSlot.getValuesAsync(filter.storageSlot.toString()))
232
- : await toArray(this.#nullifiedNotesByContract.getValuesAsync(filter.contractAddress.toString())),
233
- notes: this.#nullifiedNotes,
234
- });
272
+ // If status is ACTIVE_OR_NULLIFIED we add nullified notes as candidates on top of the default active ones.
273
+ if (filter.status === NoteStatus.ACTIVE_OR_NULLIFIED) {
274
+ const nullifiedIds = filter.storageSlot
275
+ ? await toArray(this.#nullifiedNotesByStorageSlot.getValuesAsync(filter.storageSlot.toString()))
276
+ : await toArray(this.#nullifiedNotesByContract.getValuesAsync(filter.contractAddress.toString()));
277
+
278
+ const setOfScopes = new Set(filter.scopes.map(s => s.toString() as string));
279
+ const filteredNullifiedIds = new Set<string>();
280
+
281
+ for (const noteId of nullifiedIds) {
282
+ const scopeList = await toArray(this.#nullifiedNotesToScope.getValuesAsync(noteId));
283
+ if (scopeList.some(scope => setOfScopes.has(scope))) {
284
+ filteredNullifiedIds.add(noteId);
285
+ }
286
+ }
287
+
288
+ if (filteredNullifiedIds.size > 0) {
289
+ candidateNoteSources.push({
290
+ ids: filteredNullifiedIds,
291
+ notes: this.#nullifiedNotes,
292
+ });
293
+ }
235
294
  }
236
295
 
237
296
  const result: NoteDao[] = [];
@@ -247,18 +306,10 @@ export class NoteDataProvider implements DataProvider {
247
306
  continue;
248
307
  }
249
308
 
250
- if (filter.txHash && !note.txHash.equals(filter.txHash)) {
251
- continue;
252
- }
253
-
254
309
  if (filter.storageSlot && !note.storageSlot.equals(filter.storageSlot!)) {
255
310
  continue;
256
311
  }
257
312
 
258
- if (filter.recipient && !note.recipient.equals(filter.recipient)) {
259
- continue;
260
- }
261
-
262
313
  if (filter.siloedNullifier && !note.siloedNullifier.equals(filter.siloedNullifier)) {
263
314
  continue;
264
315
  }
@@ -270,7 +321,18 @@ export class NoteDataProvider implements DataProvider {
270
321
  return result;
271
322
  }
272
323
 
273
- removeNullifiedNotes(nullifiers: InBlock<Fr>[], recipient: AztecAddress): Promise<NoteDao[]> {
324
+ /**
325
+ * Transitions notes from "active" to "nullified" state.
326
+ *
327
+ * This operation processes a batch of nullifiers to mark the corresponding notes
328
+ * as spent/nullified. The operation is atomic - if any nullifier is not found,
329
+ * the entire operation fails and no notes are modified.
330
+ *
331
+ * @param nullifiers - Array of nullifiers with their block numbers to process
332
+ * @returns Promise resolving to array of nullified NoteDao objects
333
+ * @throws Error if any nullifier is not found in the active notes
334
+ */
335
+ applyNullifiers(nullifiers: InBlock<Fr>[]): Promise<NoteDao[]> {
274
336
  if (nullifiers.length === 0) {
275
337
  return Promise.resolve([]);
276
338
  }
@@ -280,21 +342,25 @@ export class NoteDataProvider implements DataProvider {
280
342
 
281
343
  for (const blockScopedNullifier of nullifiers) {
282
344
  const { data: nullifier, l2BlockNumber: blockNumber } = blockScopedNullifier;
283
- const noteIndex = await this.#nullifierToNoteId.getAsync(nullifier.toString());
345
+ const nullifierKey = nullifier.toString();
346
+
347
+ const noteIndex = await this.#nullifierToNoteId.getAsync(nullifierKey);
284
348
  if (!noteIndex) {
285
- throw new Error('Nullifier not found in removeNullifiedNotes');
349
+ // Check if already nullified?
350
+ const alreadyNullified = await this.#nullifiedNotesByNullifier.getAsync(nullifierKey);
351
+ if (alreadyNullified) {
352
+ throw new Error(`Nullifier already applied in applyNullifiers`);
353
+ }
354
+ throw new Error('Nullifier not found in applyNullifiers');
286
355
  }
287
356
 
288
357
  const noteBuffer = noteIndex ? await this.#notes.getAsync(noteIndex) : undefined;
289
358
 
290
359
  if (!noteBuffer) {
291
- throw new Error('Note not found in removeNullifiedNotes');
360
+ throw new Error('Note not found in applyNullifiers');
292
361
  }
293
362
  const noteScopes = (await toArray(this.#notesToScope.getValuesAsync(noteIndex))) ?? [];
294
363
  const note = NoteDao.fromBuffer(noteBuffer);
295
- if (!note.recipient.equals(recipient)) {
296
- throw new Error("Tried to nullify someone else's note");
297
- }
298
364
 
299
365
  nullifiedNotes.push(note);
300
366
 
@@ -304,8 +370,6 @@ export class NoteDataProvider implements DataProvider {
304
370
  const scopes = await toArray(this.#scopes.keysAsync());
305
371
 
306
372
  for (const scope of scopes) {
307
- await this.#notesByRecipientAndScope.get(scope)!.deleteValue(note.recipient.toString(), noteIndex);
308
- await this.#notesByTxHashAndScope.get(scope)!.deleteValue(note.txHash.toString(), noteIndex);
309
373
  await this.#notesByContractAndScope.get(scope)!.deleteValue(note.contractAddress.toString(), noteIndex);
310
374
  await this.#notesByStorageSlotAndScope.get(scope)!.deleteValue(note.storageSlot.toString(), noteIndex);
311
375
  }
@@ -319,8 +383,6 @@ export class NoteDataProvider implements DataProvider {
319
383
  await this.#nullifiersByBlockNumber.set(blockNumber, nullifier.toString());
320
384
  await this.#nullifiedNotesByContract.set(note.contractAddress.toString(), noteIndex);
321
385
  await this.#nullifiedNotesByStorageSlot.set(note.storageSlot.toString(), noteIndex);
322
- await this.#nullifiedNotesByTxHash.set(note.txHash.toString(), noteIndex);
323
- await this.#nullifiedNotesByRecipient.set(note.recipient.toString(), noteIndex);
324
386
  await this.#nullifiedNotesByNullifier.set(nullifier.toString(), noteIndex);
325
387
 
326
388
  await this.#nullifierToNoteId.delete(nullifier.toString());
@@ -328,23 +390,4 @@ export class NoteDataProvider implements DataProvider {
328
390
  return nullifiedNotes;
329
391
  });
330
392
  }
331
-
332
- async getSize() {
333
- const scopes = await toArray(this.#scopes.keysAsync());
334
- const contractAddresses = new Set<string>();
335
-
336
- // Collect all unique contract addresses across all scopes
337
- for (const scope of scopes) {
338
- const addresses = await toArray(this.#notesByContractAndScope.get(scope)!.keysAsync());
339
- addresses.forEach(addr => contractAddresses.add(addr));
340
- }
341
-
342
- // Get all notes for each contract address
343
- const allNotes = await Promise.all(
344
- Array.from(contractAddresses).map(addr => this.getNotes({ contractAddress: AztecAddress.fromString(addr) })),
345
- );
346
-
347
- // Reduce all notes to get total size
348
- return allNotes.flat().reduce((sum, note) => sum + note.getSize(), 0);
349
- }
350
393
  }
@@ -6,8 +6,6 @@ import type { EventSelector } from '@aztec/stdlib/abi';
6
6
  import type { AztecAddress } from '@aztec/stdlib/aztec-address';
7
7
  import type { TxHash } from '@aztec/stdlib/tx';
8
8
 
9
- import type { DataProvider } from '../data_provider.js';
10
-
11
9
  interface PrivateEventEntry {
12
10
  msgContent: Buffer;
13
11
  blockNumber: number;
@@ -17,7 +15,7 @@ interface PrivateEventEntry {
17
15
  /**
18
16
  * Stores decrypted private event logs.
19
17
  */
20
- export class PrivateEventDataProvider implements DataProvider {
18
+ export class PrivateEventDataProvider {
21
19
  #store: AztecAsyncKVStore;
22
20
  /** Array storing the actual private event log entries containing the log content and block number */
23
21
  #eventLogs: AztecAsyncArray<PrivateEventEntry>;
@@ -127,8 +125,4 @@ export class PrivateEventDataProvider implements DataProvider {
127
125
 
128
126
  return events.map(e => e.msgContent);
129
127
  }
130
-
131
- getSize(): Promise<number> {
132
- return this.#eventLogs.lengthAsync();
133
- }
134
128
  }
@@ -1,9 +1,7 @@
1
1
  import type { AztecAsyncKVStore, AztecAsyncSingleton } from '@aztec/kv-store';
2
2
  import { BlockHeader } from '@aztec/stdlib/tx';
3
3
 
4
- import type { DataProvider } from '../data_provider.js';
5
-
6
- export class SyncDataProvider implements DataProvider {
4
+ export class SyncDataProvider {
7
5
  #store: AztecAsyncKVStore;
8
6
  #synchronizedHeader: AztecAsyncSingleton<Buffer>;
9
7
 
@@ -33,8 +31,4 @@ export class SyncDataProvider implements DataProvider {
33
31
 
34
32
  return BlockHeader.fromBuffer(headerBuffer);
35
33
  }
36
-
37
- async getSize(): Promise<number> {
38
- return (await this.#synchronizedHeader.getAsync())?.length ?? 0;
39
- }
40
34
  }