@aztec/pxe 4.0.0-nightly.20250907 → 4.0.0-nightly.20260107

package/src/storage/{address_data_provider/address_data_provider.ts → address_store/address_store.ts}

@@ -3,9 +3,7 @@ import type { AztecAsyncArray, AztecAsyncKVStore, AztecAsyncMap } from '@aztec/k
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 import { CompleteAddress } from '@aztec/stdlib/contract';
 
-import type { DataProvider } from '../data_provider.js';
-
-export class AddressDataProvider implements DataProvider {
+export class AddressStore {
   #store: AztecAsyncKVStore;
   #completeAddresses: AztecAsyncArray<Buffer>;
   #completeAddressIndex: AztecAsyncMap<string, number>;
@@ -64,8 +62,4 @@ export class AddressDataProvider implements DataProvider {
       (await toArray(this.#completeAddresses.valuesAsync())).map(v => CompleteAddress.fromBuffer(v)),
     );
   }
-
-  async getSize(): Promise<number> {
-    return (await this.#completeAddresses.lengthAsync()) * CompleteAddress.SIZE_IN_BYTES;
-  }
 }

package/src/storage/address_store/index.ts

@@ -0,0 +1 @@
+export { AddressStore } from './address_store.js';

package/src/storage/{sync_data_provider/sync_data_provider.ts → anchor_block_store/anchor_block_store.ts}

@@ -1,9 +1,7 @@
 import type { AztecAsyncKVStore, AztecAsyncSingleton } from '@aztec/kv-store';
 import { BlockHeader } from '@aztec/stdlib/tx';
 
-import type { DataProvider } from '../data_provider.js';
-
-export class SyncDataProvider implements DataProvider {
+export class AnchorBlockStore {
   #store: AztecAsyncKVStore;
   #synchronizedHeader: AztecAsyncSingleton<Buffer>;
 
@@ -16,25 +14,12 @@ export class SyncDataProvider implements DataProvider {
     await this.#synchronizedHeader.set(header.toBuffer());
   }
 
-  async getBlockNumber(): Promise<number> {
-    const headerBuffer = await this.#synchronizedHeader.getAsync();
-    if (!headerBuffer) {
-      throw new Error(`Trying to get block number with a not-yet-synchronized PXE - this should never happen`);
-    }
-
-    return BlockHeader.fromBuffer(headerBuffer).globalVariables.blockNumber;
-  }
-
   async getBlockHeader(): Promise<BlockHeader> {
     const headerBuffer = await this.#synchronizedHeader.getAsync();
     if (!headerBuffer) {
-      throw new Error(`Header not set`);
+      throw new Error(`Trying to get block header with a not-yet-synchronized PXE - this should never happen`);
     }
 
     return BlockHeader.fromBuffer(headerBuffer);
   }
-
-  async getSize(): Promise<number> {
-    return (await this.#synchronizedHeader.getAsync())?.length ?? 0;
-  }
 }

package/src/storage/anchor_block_store/index.ts

@@ -0,0 +1 @@
+export { AnchorBlockStore } from './anchor_block_store.js';

package/src/storage/{capsule_data_provider/capsule_data_provider.ts → capsule_store/capsule_store.ts}

@@ -1,12 +1,9 @@
-import { Fr } from '@aztec/foundation/fields';
-import { toArray } from '@aztec/foundation/iterable';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { type Logger, createLogger } from '@aztec/foundation/log';
 import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 
-import type { DataProvider } from '../data_provider.js';
-
-export class CapsuleDataProvider implements DataProvider {
+export class CapsuleStore {
   #store: AztecAsyncKVStore;
 
   // Arbitrary data stored by contracts. Key is computed as `${contractAddress}:${key}`
@@ -22,10 +19,26 @@ export class CapsuleDataProvider implements DataProvider {
     this.logger = createLogger('pxe:capsule-data-provider');
   }
 
+  /**
+   * Stores arbitrary information in a per-contract non-volatile database, which can later be retrieved with `loadCapsule`.
+   * * If data was already stored at this slot, it is overwritten.
+   * @param contractAddress - The contract address to scope the data under.
+   * @param slot - The slot in the database in which to store the value. Slots need not be contiguous.
+   * @param capsule - An array of field elements representing the capsule.
+   * @remarks A capsule is a "blob" of data that is passed to the contract through an oracle. It works similarly
+   * to public contract storage in that it's indexed by the contract address and storage slot but instead of the global
+   * network state it's backed by local PXE db.
+   */
   async storeCapsule(contractAddress: AztecAddress, slot: Fr, capsule: Fr[]): Promise<void> {
     await this.#capsules.set(dbSlotToKey(contractAddress, slot), Buffer.concat(capsule.map(value => value.toBuffer())));
   }
 
+  /**
+   * Returns data previously stored via `storeCapsule` in the per-contract non-volatile database.
+   * @param contractAddress - The contract address under which the data is scoped.
+   * @param slot - The slot in the database to read.
+   * @returns The stored data or `null` if no data is stored under the slot.
+   */
   async loadCapsule(contractAddress: AztecAddress, slot: Fr): Promise<Fr[] | null> {
     const dataBuffer = await this.#capsules.getAsync(dbSlotToKey(contractAddress, slot));
     if (!dataBuffer) {
@@ -39,10 +52,26 @@ export class CapsuleDataProvider implements DataProvider {
     return capsule;
   }
 
+  /**
+   * Deletes data in the per-contract non-volatile database. Does nothing if no data was present.
+   * @param contractAddress - The contract address under which the data is scoped.
+   * @param slot - The slot in the database to delete.
+   */
   async deleteCapsule(contractAddress: AztecAddress, slot: Fr): Promise<void> {
     await this.#capsules.delete(dbSlotToKey(contractAddress, slot));
   }
 
+  /**
+   * Copies a number of contiguous entries in the per-contract non-volatile database. This allows for efficient data
+   * structures by avoiding repeated calls to `loadCapsule` and `storeCapsule`.
+   * Supports overlapping source and destination regions (which will result in the overlapped source values being
+   * overwritten). All copied slots must exist in the database (i.e. have been stored and not deleted)
+   *
+   * @param contractAddress - The contract address under which the data is scoped.
+   * @param srcSlot - The first slot to copy from.
+   * @param dstSlot - The first slot to copy to.
+   * @param numEntries - The number of entries to copy.
+   */
   copyCapsule(contractAddress: AztecAddress, srcSlot: Fr, dstSlot: Fr, numEntries: number): Promise<void> {
     return this.#store.transactionAsync(async () => {
       // In order to support overlapping source and destination regions, we need to check the relative positions of source
@@ -139,13 +168,6 @@ export class CapsuleDataProvider implements DataProvider {
       }
     });
   }
-
-  public async getSize() {
-    return (await toArray(this.#capsules.valuesAsync())).reduce(
-      (sum, value) => sum + value.length * Fr.SIZE_IN_BYTES,
-      0,
-    );
-  }
 }
 
 function dbSlotToKey(contractAddress: AztecAddress, slot: Fr): string {

package/src/storage/capsule_store/index.ts

@@ -0,0 +1 @@
+export { CapsuleStore } from './capsule_store.js';

package/src/storage/{contract_data_provider/contract_data_provider.ts → contract_store/contract_store.ts}

@@ -1,17 +1,21 @@
-import type { Fr } from '@aztec/foundation/fields';
+import type { FUNCTION_TREE_HEIGHT } from '@aztec/constants';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 import { toArray } from '@aztec/foundation/iterable';
 import type { MembershipWitness } from '@aztec/foundation/trees';
 import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
+import { isProtocolContract } from '@aztec/protocol-contracts';
 import {
   type ContractArtifact,
   type FunctionAbi,
   type FunctionArtifact,
   type FunctionArtifactWithContractName,
+  FunctionCall,
   type FunctionDebugMetadata,
   FunctionSelector,
   FunctionType,
   contractArtifactFromBuffer,
   contractArtifactToBuffer,
+  encodeArguments,
   getFunctionDebugMetadata,
 } from '@aztec/stdlib/abi';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
@@ -22,17 +26,16 @@ import {
   getContractClassFromArtifact,
 } from '@aztec/stdlib/contract';
 
-import type { DataProvider } from '../data_provider.js';
 import { PrivateFunctionsTree } from './private_functions_tree.js';
 
 /**
- * ContractDataProvider serves as a data manager and retriever for Aztec.nr contracts.
+ * ContractStore serves as a data manager and retriever for Aztec.nr contracts.
  * It provides methods to obtain contract addresses, function ABI, bytecode, and membership witnesses
  * from a given contract address and function selector. The class maintains a cache of ContractTree instances
  * to efficiently serve the requested data. It interacts with the ContractDatabase and AztecNode to fetch
  * the required information and facilitate cryptographic proof generation.
  */
-export class ContractDataProvider implements DataProvider {
+export class ContractStore {
   /** Map from contract class id to private function tree. */
   // TODO: Update it to be LRU cache so that it doesn't keep all the data all the time.
   #privateFunctionTrees: Map<string, PrivateFunctionsTree> = new Map();
@@ -176,6 +179,21 @@ export class ContractDataProvider implements DataProvider {
     return fnArtifact && { ...fnArtifact, contractName: artifact.name };
   }
 
+  public async getFunctionArtifactWithDebugMetadata(
+    contractAddress: AztecAddress,
+    selector: FunctionSelector,
+  ): Promise<FunctionArtifactWithContractName> {
+    const artifact = await this.getFunctionArtifact(contractAddress, selector);
+    if (!artifact) {
+      throw new Error(`Function artifact not found for contract ${contractAddress} and selector ${selector}.`);
+    }
+    const debug = await this.getFunctionDebugMetadata(contractAddress, selector);
+    return {
+      ...artifact,
+      debug,
+    };
+  }
+
   public async getPublicFunctionArtifact(
     contractAddress: AztecAddress,
   ): Promise<FunctionArtifactWithContractName | undefined> {
@@ -184,23 +202,6 @@ export class ContractDataProvider implements DataProvider {
     return fnArtifact && { ...fnArtifact, contractName: artifact.name };
   }
 
-  /**
-   * Retrieves the artifact of a specified function within a given contract.
-   * The function is identified by its name, which is unique within a contract.
-   * Throws if the contract has not been added to the database.
-   *
-   * @param contractAddress - The AztecAddress representing the contract containing the function.
-   * @param functionName - The name of the function.
-   * @returns The corresponding function's artifact as an object
-   */
-  public async getFunctionArtifactByName(
-    contractAddress: AztecAddress,
-    functionName: string,
-  ): Promise<FunctionArtifact | undefined> {
-    const artifact = await this.#getContractArtifactByAddress(contractAddress);
-    return artifact?.functions.find(fn => fn.name === functionName);
-  }
-
   public async getFunctionAbi(
     contractAddress: AztecAddress,
     selector: FunctionSelector,
@@ -248,7 +249,7 @@ export class ContractDataProvider implements DataProvider {
   public async getFunctionMembershipWitness(
     contractClassId: Fr,
     selector: FunctionSelector,
-  ): Promise<MembershipWitness<5> | undefined> {
+  ): Promise<MembershipWitness<typeof FUNCTION_TREE_HEIGHT> | undefined> {
     const tree = await this.#getPrivateFunctionTreeForClassId(contractClassId);
     return tree?.getFunctionMembershipWitness(selector);
   }
@@ -264,12 +265,6 @@ export class ContractDataProvider implements DataProvider {
     return `${artifact?.name ?? contractAddress}:${fnArtifact?.name ?? selector}`;
   }
 
-  public async getSize() {
-    return (await toArray(this.#contractInstances.valuesAsync()))
-      .concat(await toArray(this.#contractArtifacts.valuesAsync()))
-      .reduce((sum, value) => sum + value.length, 0);
-  }
-
   async #findFunctionArtifactBySelector(
     artifact: ContractArtifact,
     selector: FunctionSelector,
@@ -297,4 +292,48 @@ export class ContractDataProvider implements DataProvider {
       }
     }
   }
+
+  public async getFunctionCall(functionName: string, args: any[], to: AztecAddress): Promise<FunctionCall> {
+    const contract = await this.getContract(to);
+    if (!contract) {
+      throw new Error(
+        `Unknown contract ${to}: add it to PXE by calling server.addContracts(...).\nSee docs for context: https://docs.aztec.network/developers/resources/debugging/aztecnr-errors#unknown-contract-0x0-add-it-to-pxe-by-calling-serveraddcontracts`,
+      );
+    }
+
+    const functionDao = contract.functions.find(f => f.name === functionName);
+    if (!functionDao) {
+      throw new Error(`Unknown function ${functionName} in contract ${contract.name}.`);
+    }
+
+    return {
+      name: functionDao.name,
+      args: encodeArguments(functionDao, args),
+      selector: await FunctionSelector.fromNameAndParameters(functionDao.name, functionDao.parameters),
+      type: functionDao.functionType,
+      to,
+      hideMsgSender: false,
+      isStatic: functionDao.isStatic,
+      returnTypes: functionDao.returnTypes,
+    };
+  }
+
+  // Synchronize target contract data
+  public async syncPrivateState(
+    contractAddress: AztecAddress,
+    functionToInvokeAfterSync: FunctionSelector | null,
+    utilityExecutor: (privateSyncCall: FunctionCall) => Promise<any>,
+  ) {
+    // Protocol contracts don't have private state to sync
+    if (!isProtocolContract(contractAddress)) {
+      const syncPrivateStateFunctionCall = await this.getFunctionCall('sync_private_state', [], contractAddress);
+      if (functionToInvokeAfterSync && functionToInvokeAfterSync.equals(syncPrivateStateFunctionCall.selector)) {
+        throw new Error(
+          'Forbidden `sync_private_state` invocation. `sync_private_state` can only be invoked by PXE, manual execution can lead to inconsistencies.',
+        );
+      }
+
+      return utilityExecutor(syncPrivateStateFunctionCall);
+    }
+  }
 }

package/src/storage/contract_store/index.ts

@@ -0,0 +1 @@
+export { ContractStore } from './contract_store.js';

package/src/storage/{contract_data_provider → contract_store}/private_functions_tree.ts

@@ -1,5 +1,5 @@
 import { FUNCTION_TREE_HEIGHT } from '@aztec/constants';
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { assertLength } from '@aztec/foundation/serialize';
 import { MembershipWitness, type MerkleTree } from '@aztec/foundation/trees';
 import { type ContractArtifact, FunctionSelector, FunctionType } from '@aztec/stdlib/abi';

package/src/storage/index.ts

@@ -1,9 +1,8 @@
-export * from './address_data_provider/index.js';
-export * from './capsule_data_provider/index.js';
-export * from './contract_data_provider/index.js';
-export * from './note_data_provider/index.js';
-export * from './sync_data_provider/index.js';
-export * from './tagging_data_provider/index.js';
-export * from './data_provider.js';
+export * from './address_store/index.js';
+export * from './capsule_store/index.js';
+export * from './contract_store/index.js';
+export * from './note_store/index.js';
+export * from './anchor_block_store/index.js';
+export * from './tagging_store/index.js';
 export * from './metadata.js';
-export * from './private_event_data_provider/private_event_data_provider.js';
+export * from './private_event_store/private_event_store.js';

package/src/storage/note_store/index.ts

@@ -0,0 +1,2 @@
+export { NoteDao } from '@aztec/stdlib/note';
+export { NoteStore } from './note_store.js';