@aztec/pxe 0.0.1-commit.9ef841308 → 0.0.1-commit.a4600f49

package/src/storage/backwards_compatibility_tests/store_spy.ts

@@ -0,0 +1,73 @@
+import type {
+  AztecAsyncArray,
+  AztecAsyncCounter,
+  AztecAsyncKVStore,
+  AztecAsyncMap,
+  AztecAsyncMultiMap,
+  AztecAsyncSet,
+  AztecAsyncSingleton,
+  Key,
+} from '@aztec/kv-store';
+
+type Value = NonNullable<any>;
+
+/** The kind of named sub-store opened on an `AztecAsyncKVStore`. */
+export type StoreKind = 'map' | 'multimap' | 'array' | 'singleton' | 'set' | 'counter';
+
+/** A single recorded `open*()` call against a spied store. */
+export interface OpenedStoreEntry {
+  name: string;
+  kind: StoreKind;
+}
+
+/** A spied `AztecAsyncKVStore` together with a function that returns the sorted log of `open*()` calls. */
+export interface StoreSpy {
+  store: AztecAsyncKVStore;
+  getOpenedStores: () => OpenedStoreEntry[];
+}
+
+/**
+ * Wraps an `AztecAsyncKVStore` so every `openMap`/`openMultiMap`/`openArray`/`openSingleton`/`openSet`/`openCounter`
+ * call is recorded before being delegated to the inner store.
+ */
+export function createStoreSpy(inner: AztecAsyncKVStore): StoreSpy {
+  const entries: OpenedStoreEntry[] = [];
+
+  const store: AztecAsyncKVStore = {
+    openMap<K extends Key, V extends Value>(name: string): AztecAsyncMap<K, V> {
+      entries.push({ name, kind: 'map' });
+      return inner.openMap<K, V>(name);
+    },
+    openMultiMap<K extends Key, V extends Value>(name: string): AztecAsyncMultiMap<K, V> {
+      entries.push({ name, kind: 'multimap' });
+      return inner.openMultiMap<K, V>(name);
+    },
+    openArray<T extends Value>(name: string): AztecAsyncArray<T> {
+      entries.push({ name, kind: 'array' });
+      return inner.openArray<T>(name);
+    },
+    openSingleton<T extends Value>(name: string): AztecAsyncSingleton<T> {
+      entries.push({ name, kind: 'singleton' });
+      return inner.openSingleton<T>(name);
+    },
+    openSet<K extends Key>(name: string): AztecAsyncSet<K> {
+      entries.push({ name, kind: 'set' });
+      return inner.openSet<K>(name);
+    },
+    openCounter<K extends Key>(name: string): AztecAsyncCounter<K> {
+      entries.push({ name, kind: 'counter' });
+      return inner.openCounter<K>(name);
+    },
+    transactionAsync: callback => inner.transactionAsync(callback),
+    clear: () => inner.clear(),
+    delete: () => inner.delete(),
+    estimateSize: () => inner.estimateSize(),
+    close: () => inner.close(),
+    backupTo: (dstPath, compact) => inner.backupTo(dstPath, compact),
+  };
+
+  const getOpenedStores = () =>
+    [...entries].sort((a, b) => (a.name === b.name ? a.kind.localeCompare(b.kind) : a.name.localeCompare(b.name)));
+
+  return { store, getOpenedStores };
+}

package/src/storage/capsule_store/capsule_service.ts

@@ -2,7 +2,7 @@ import type { Fr } from '@aztec/foundation/curves/bn254';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import type { Capsule } from '@aztec/stdlib/tx';
 
-import type { AccessScopes } from '../../access_scopes.js';
+import { assertAllowedScope } from '../allowed_scopes.js';
 import type { CapsuleStore } from './capsule_store.js';
 
 /**
@@ -10,10 +10,15 @@ import type { CapsuleStore } from './capsule_store.js';
  * allowed scopes list before delegating to the underlying store.
  */
 export class CapsuleService {
+  private readonly allowedScopes: AztecAddress[];
+
   constructor(
     private readonly capsuleStore: CapsuleStore,
-    private readonly allowedScopes: AccessScopes,
-  ) {}
+    allowedScopes: AztecAddress[],
+  ) {
+    // The zero address denotes the global capsule scope, which is always permitted.
+    this.allowedScopes = [...allowedScopes, AztecAddress.ZERO];
+  }
 
   setCapsule(contractAddress: AztecAddress, slot: Fr, capsule: Fr[], jobId: string, scope: AztecAddress) {
     assertAllowedScope(scope, this.allowedScopes);
@@ -78,14 +83,3 @@ export class CapsuleService {
     return this.capsuleStore.setCapsuleArray(contractAddress, baseSlot, content, jobId, scope);
   }
 }
-
-function assertAllowedScope(scope: AztecAddress, allowedScopes: AccessScopes) {
-  if (allowedScopes === 'ALL_SCOPES' || scope.equals(AztecAddress.ZERO)) {
-    return;
-  }
-  if (!allowedScopes.some(allowed => allowed.equals(scope))) {
-    throw new Error(
-      `Scope ${scope.toString()} is not in the allowed scopes list: [${allowedScopes.map(s => s.toString()).join(', ')}]. See https://docs.aztec.network/errors/10`,
-    );
-  }
-}

package/src/storage/capsule_store/capsule_store.ts

@@ -148,7 +148,17 @@ export class CapsuleStore implements StagedStore {
    * @param slot - The slot in the database to read.
    * @returns The stored data or `null` if no data is stored under the slot.
    */
-  async getCapsule(contractAddress: AztecAddress, slot: Fr, jobId: string, scope: AztecAddress): Promise<Fr[] | null> {
+  getCapsule(contractAddress: AztecAddress, slot: Fr, jobId: string, scope: AztecAddress): Promise<Fr[] | null> {
+    return this.#store.transactionAsync(() => this.#getCapsuleInternal(contractAddress, slot, jobId, scope));
+  }
+
+  /** Same as getCapsule but without its own transaction, for use inside an existing transactionAsync. */
+  async #getCapsuleInternal(
+    contractAddress: AztecAddress,
+    slot: Fr,
+    jobId: string,
+    scope: AztecAddress,
+  ): Promise<Fr[] | null> {
     const dataBuffer = await this.#getFromStage(jobId, dbSlotToKey(contractAddress, slot, scope));
     if (!dataBuffer) {
       this.logger.trace(`Data not found for contract ${contractAddress.toString()} and slot ${slot.toString()}`);
@@ -240,7 +250,7 @@ export class CapsuleStore implements StagedStore {
     // and not using a transaction here would heavily impact performance.
     return this.#store.transactionAsync(async () => {
       // Load current length, defaulting to 0 if not found
-      const lengthData = await this.getCapsule(contractAddress, baseSlot, jobId, scope);
+      const lengthData = await this.#getCapsuleInternal(contractAddress, baseSlot, jobId, scope);
       const currentLength = lengthData ? lengthData[0].toNumber() : 0;
 
       // Store each capsule at consecutive slots after baseSlot + 1 + currentLength
@@ -263,14 +273,14 @@ export class CapsuleStore implements StagedStore {
     // of jobs: different calls running concurrently on the same contract may cause trouble.
     return this.#store.transactionAsync(async () => {
       // Load length, defaulting to 0 if not found
-      const maybeLength = await this.getCapsule(contractAddress, baseSlot, jobId, scope);
+      const maybeLength = await this.#getCapsuleInternal(contractAddress, baseSlot, jobId, scope);
       const length = maybeLength ? maybeLength[0].toBigInt() : 0n;
 
       const values: Fr[][] = [];
 
       // Read each capsule at consecutive slots after baseSlot
       for (let i = 0; i < length; i++) {
-        const currentValue = await this.getCapsule(contractAddress, arraySlot(baseSlot, i), jobId, scope);
+        const currentValue = await this.#getCapsuleInternal(contractAddress, arraySlot(baseSlot, i), jobId, scope);
         if (currentValue == undefined) {
           throw new Error(
             `Expected non-empty value at capsule array in base slot ${baseSlot} at index ${i} for contract ${contractAddress}`,
@@ -295,7 +305,7 @@ export class CapsuleStore implements StagedStore {
     // of jobs: different calls running concurrently on the same contract may cause trouble.
     return this.#store.transactionAsync(async () => {
       // Load current length, defaulting to 0 if not found
-      const maybeLength = await this.getCapsule(contractAddress, baseSlot, jobId, scope);
+      const maybeLength = await this.#getCapsuleInternal(contractAddress, baseSlot, jobId, scope);
       const originalLength = maybeLength ? maybeLength[0].toNumber() : 0;
 
       // Set the new length

package/src/storage/contract_store/contract_store.ts

@@ -6,8 +6,6 @@ import type { MembershipWitness } from '@aztec/foundation/trees';
 import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
 import {
   type ContractArtifact,
-  type FunctionAbi,
-  type FunctionArtifact,
   type FunctionArtifactWithContractName,
   FunctionCall,
   type FunctionDebugMetadata,
@@ -16,14 +14,16 @@ import {
   contractArtifactFromBuffer,
   contractArtifactToBuffer,
   encodeArguments,
+  findFunctionAbiBySelector,
+  findFunctionArtifactBySelector,
   getFunctionDebugMetadata,
 } from '@aztec/stdlib/abi';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import {
   type ContractClassIdPreimage,
   type ContractClassWithId,
-  type ContractInstanceWithAddress,
-  SerializableContractInstance,
+  type ContractInstancePreimageWithAddress,
+  SerializableContractInstancePreimage,
   getContractClassFromArtifact,
 } from '@aztec/stdlib/contract';
 
@@ -111,9 +111,6 @@ export class ContractStore {
   // TODO: Update it to be LRU cache so that it doesn't keep all the data all the time.
   #contractArtifactCache: Map<string, ContractArtifact> = new Map();
 
-  /** Map from contract address to contract class id (avoids KV round-trip on hot path). */
-  #contractClassIdMap: Map<string, Fr> = new Map();
-
   #store: AztecAsyncKVStore;
   #contractArtifacts: AztecAsyncMap<string, Buffer>;
   #contractClassData: AztecAsyncMap<string, Buffer>;
@@ -130,9 +127,10 @@ export class ContractStore {
 
   /**
    * Registers a new contract artifact and its corresponding class data.
-   * IMPORTANT: This method does not verify that the provided artifact matches the class data or that the class id matches the artifact.
-   * It is the caller's responsibility to ensure the consistency and correctness of the provided data.
-   * This is done to avoid redundant, expensive contract class computations
+   *
+   * IMPORTANT: This method does not verify that the provided artifact matches the class data or that the class id
+   * matches the artifact. It is the caller's responsibility to ensure the consistency and correctness of the provided
+   * data. This is done to avoid redundant, expensive contract class computations.
    */
   public async addContractArtifact(
     contract: ContractArtifact,
@@ -167,29 +165,17 @@ export class ContractStore {
     return contractClass.id;
   }
 
-  async addContractInstance(contract: ContractInstanceWithAddress): Promise<void> {
-    this.#contractClassIdMap.set(contract.address.toString(), contract.currentContractClassId);
-
-    await this.#contractInstances.set(
-      contract.address.toString(),
-      new SerializableContractInstance(contract).toBuffer(),
-    );
+  async addContractInstance(contract: ContractInstancePreimageWithAddress): Promise<void> {
+    await this.#store.transactionAsync(async () => {
+      await this.#contractInstances.set(
+        contract.address.toString(),
+        new SerializableContractInstancePreimage(contract).toBuffer(),
+      );
+    });
   }
 
   // Private getters
 
-  async #getContractClassId(contractAddress: AztecAddress): Promise<Fr | undefined> {
-    const key = contractAddress.toString();
-    if (!this.#contractClassIdMap.has(key)) {
-      const instance = await this.getContractInstance(contractAddress);
-      if (!instance) {
-        return;
-      }
-      this.#contractClassIdMap.set(key, instance.currentContractClassId);
-    }
-    return this.#contractClassIdMap.get(key);
-  }
-
   async #getPrivateFunctionTreeForClassId(classId: Fr): Promise<PrivateFunctionsTree | undefined> {
     if (!this.#privateFunctionTrees.has(classId.toString())) {
       const artifact = await this.getContractArtifact(classId);
@@ -202,25 +188,20 @@ export class ContractStore {
     return this.#privateFunctionTrees.get(classId.toString())!;
   }
 
-  async #getArtifactByAddress(contractAddress: AztecAddress): Promise<ContractArtifact | undefined> {
-    const classId = await this.#getContractClassId(contractAddress);
-    return classId && this.getContractArtifact(classId);
-  }
-
   // Public getters
 
   getContractsAddresses(): Promise<AztecAddress[]> {
     return this.#store.transactionAsync(async () => {
       const keys = await toArray(this.#contractInstances.keysAsync());
-      return keys.map(AztecAddress.fromString);
+      return keys.map(AztecAddress.fromStringUnsafe);
     });
   }
 
-  /** Returns a contract instance for a given address. */
-  public getContractInstance(contractAddress: AztecAddress): Promise<ContractInstanceWithAddress | undefined> {
+  /** Returns the address preimage of a given address. */
+  public getContractInstance(contractAddress: AztecAddress): Promise<ContractInstancePreimageWithAddress | undefined> {
     return this.#store.transactionAsync(async () => {
       const contract = await this.#contractInstances.getAsync(contractAddress.toString());
-      return contract && SerializableContractInstance.fromBuffer(contract).withAddress(contractAddress);
+      return contract && SerializableContractInstancePreimage.fromBuffer(contract).withAddress(contractAddress);
     });
   }
 
@@ -246,7 +227,7 @@ export class ContractStore {
     contractClassId: Fr,
   ): Promise<(ContractClassWithId & ContractClassIdPreimage) | undefined> {
     const key = contractClassId.toString();
-    const buf = await this.#contractClassData.getAsync(key);
+    const buf = await this.#store.transactionAsync(() => this.#contractClassData.getAsync(key));
     if (!buf) {
       return undefined;
     }
@@ -259,93 +240,78 @@ export class ContractStore {
     return { ...classData, packedBytecode };
   }
 
-  public async getContract(
-    address: AztecAddress,
-  ): Promise<(ContractInstanceWithAddress & ContractArtifact) | undefined> {
-    const instance = await this.getContractInstance(address);
-    if (!instance) {
-      return;
-    }
-    const artifact = await this.getContractArtifact(instance.currentContractClassId);
-    if (!artifact) {
-      return;
-    }
-    return { ...instance, ...artifact };
-  }
-
   /**
-   * Retrieves the artifact of a specified function within a given contract.
+   * Retrieves the artifact of a specified function within a given contract class.
    *
-   * @param contractAddress - The AztecAddress representing the contract containing the function.
+   * @param contractClassId - The id of the contract class containing the function.
    * @param selector - The function selector.
-   * @returns The corresponding function's artifact as an object.
+   * @returns The corresponding function's artifact as an object, or `undefined` if the class is not registered.
    */
   public async getFunctionArtifact(
-    contractAddress: AztecAddress,
+    contractClassId: Fr,
     selector: FunctionSelector,
   ): Promise<FunctionArtifactWithContractName | undefined> {
-    const artifact = await this.#getArtifactByAddress(contractAddress);
+    const artifact = await this.getContractArtifact(contractClassId);
     if (!artifact) {
       return undefined;
     }
-    const fn = await this.#findFunctionArtifactBySelector(artifact, selector);
-    return fn && { ...fn, contractName: artifact.name };
+    const fn = assertSelectorInArtifact(artifact, await findFunctionArtifactBySelector(artifact, selector), {
+      contractClassId,
+      selector,
+    });
+    return { ...fn, contractName: artifact.name };
   }
 
+  /**
+   * Same as {@link getFunctionArtifact} but with debug metadata attached. Returns `undefined` when the class artifact
+   * is not registered.
+   */
   public async getFunctionArtifactWithDebugMetadata(
-    contractAddress: AztecAddress,
+    contractClassId: Fr,
     selector: FunctionSelector,
-  ): Promise<FunctionArtifactWithContractName> {
-    const artifact = await this.getFunctionArtifact(contractAddress, selector);
+  ): Promise<FunctionArtifactWithContractName | undefined> {
+    const artifact = await this.getContractArtifact(contractClassId);
     if (!artifact) {
-      throw new Error(`Function artifact not found for contract ${contractAddress} and selector ${selector}.`);
+      return undefined;
     }
-    const debug = await this.getFunctionDebugMetadata(contractAddress, selector);
+    const fn = assertSelectorInArtifact(artifact, await findFunctionArtifactBySelector(artifact, selector), {
+      contractClassId,
+      selector,
+    });
     return {
-      ...artifact,
-      debug,
+      ...fn,
+      contractName: artifact.name,
+      debug: getFunctionDebugMetadata(artifact, fn),
     };
   }
 
-  public async getPublicFunctionArtifact(
-    contractAddress: AztecAddress,
-  ): Promise<FunctionArtifactWithContractName | undefined> {
-    const artifact = await this.#getArtifactByAddress(contractAddress);
+  public async getPublicFunctionArtifact(contractClassId: Fr): Promise<FunctionArtifactWithContractName | undefined> {
+    const artifact = await this.getContractArtifact(contractClassId);
     const fn = artifact && artifact.functions.find(f => f.functionType === FunctionType.PUBLIC);
     return fn && { ...fn, contractName: artifact.name };
   }
 
-  public async getFunctionAbi(
-    contractAddress: AztecAddress,
-    selector: FunctionSelector,
-  ): Promise<FunctionAbi | undefined> {
-    const artifact = await this.#getArtifactByAddress(contractAddress);
-    return artifact && (await this.#findFunctionAbiBySelector(artifact, selector));
-  }
-
   /**
-   * Retrieves the debug metadata of a specified function within a given contract.
+   * Retrieves the debug metadata of a specified function within a given contract class.
    *
-   * @param contractAddress - The AztecAddress representing the contract containing the function.
+   * @param contractClassId - The id of the contract class containing the function.
    * @param selector - The function selector.
    * @returns The corresponding function's debug metadata, or undefined.
    */
   public async getFunctionDebugMetadata(
-    contractAddress: AztecAddress,
+    contractClassId: Fr,
     selector: FunctionSelector,
   ): Promise<FunctionDebugMetadata | undefined> {
-    const artifact = await this.#getArtifactByAddress(contractAddress);
+    const artifact = await this.getContractArtifact(contractClassId);
     if (!artifact) {
       return undefined;
     }
-    const fn = await this.#findFunctionArtifactBySelector(artifact, selector);
+    const fn = await findFunctionArtifactBySelector(artifact, selector);
     return fn && getFunctionDebugMetadata(artifact, fn);
   }
 
-  public async getPublicFunctionDebugMetadata(
-    contractAddress: AztecAddress,
-  ): Promise<FunctionDebugMetadata | undefined> {
-    const artifact = await this.#getArtifactByAddress(contractAddress);
+  public async getPublicFunctionDebugMetadata(contractClassId: Fr): Promise<FunctionDebugMetadata | undefined> {
+    const artifact = await this.getContractArtifact(contractClassId);
     const fn = artifact && artifact.functions.find(f => f.functionType === FunctionType.PUBLIC);
     return fn && getFunctionDebugMetadata(artifact, fn);
   }
@@ -365,52 +331,34 @@ export class ContractStore {
     return tree?.getFunctionMembershipWitness(selector);
   }
 
-  public async getDebugContractName(contractAddress: AztecAddress) {
-    const artifact = await this.#getArtifactByAddress(contractAddress);
+  public async getDebugContractName(contractClassId: Fr) {
+    const artifact = await this.getContractArtifact(contractClassId);
     return artifact?.name;
   }
 
-  public async getDebugFunctionName(contractAddress: AztecAddress, selector: FunctionSelector) {
-    const artifact = await this.#getArtifactByAddress(contractAddress);
-    const fn = artifact && (await this.#findFunctionAbiBySelector(artifact, selector));
-    return `${artifact?.name ?? contractAddress}:${fn?.name ?? selector}`;
-  }
-
-  async #findFunctionArtifactBySelector(
-    artifact: ContractArtifact,
-    selector: FunctionSelector,
-  ): Promise<FunctionArtifact | undefined> {
-    for (const fn of artifact.functions) {
-      const fnSelector = await FunctionSelector.fromNameAndParameters(fn.name, fn.parameters);
-      if (fnSelector.equals(selector)) {
-        return fn;
-      }
-    }
-  }
-
-  async #findFunctionAbiBySelector(
-    artifact: ContractArtifact,
-    selector: FunctionSelector,
-  ): Promise<FunctionAbi | undefined> {
-    for (const fn of [...artifact.functions, ...(artifact.nonDispatchPublicFunctions ?? [])]) {
-      const fnSelector = await FunctionSelector.fromNameAndParameters(fn.name, fn.parameters);
-      if (fnSelector.equals(selector)) {
-        return fn;
-      }
-    }
+  public async getDebugFunctionName(contractClassId: Fr, selector: FunctionSelector) {
+    const artifact = await this.getContractArtifact(contractClassId);
+    const fn = artifact && (await findFunctionAbiBySelector(artifact, selector));
+    return `${artifact?.name ?? contractClassId}:${fn?.name ?? selector}`;
   }
 
-  public async getFunctionCall(functionName: string, args: any[], to: AztecAddress): Promise<FunctionCall> {
-    const contract = await this.getContract(to);
-    if (!contract) {
+  public async getFunctionCall(
+    functionName: string,
+    args: any[],
+    to: AztecAddress,
+    contractClassId: Fr,
+  ): Promise<FunctionCall> {
+    const artifact = await this.getContractArtifact(contractClassId);
+    if (!artifact) {
       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`,
+        `No artifact registered for contract class ${contractClassId} (contract ${to}): register it by calling ` +
+          `wallet.registerContract(...).\nSee docs for context: https://docs.aztec.network/errors/14`,
       );
     }
 
-    const functionDao = contract.functions.find(f => f.name === functionName);
+    const functionDao = artifact.functions.find(f => f.name === functionName);
     if (!functionDao) {
-      throw new Error(`Unknown function ${functionName} in contract ${contract.name}.`);
+      throw new Error(`Unknown function ${functionName} in contract ${artifact.name}.`);
     }
 
     const selector = await FunctionSelector.fromNameAndParameters(functionDao.name, functionDao.parameters);
@@ -427,3 +375,27 @@ export class ContractStore {
     });
   }
 }
+
+/**
+ * Narrows the result of a selector lookup against a registered artifact. A missing class artifact is reported as
+ * `undefined` by the callers (an absence they can handle), but a selector that is absent from an artifact we *do* have
+ * is exceptional and throws rather than returning undefined. We cannot tell from here why the selector is missing: it
+ * may be that no such function exists in the contract (a wrong selector), or that the registered artifact does not
+ * correspond to the resolved class id (registration performs no validation, so a mismatched artifact is possible). The
+ * error names both possibilities.
+ */
+function assertSelectorInArtifact<T>(
+  artifact: ContractArtifact,
+  fn: T | undefined,
+  context: { contractClassId: Fr; selector: FunctionSelector },
+): T {
+  if (!fn) {
+    throw new Error(
+      `Function with selector ${context.selector} not found in the registered artifact for contract class ` +
+        `${context.contractClassId} (${artifact.name}). Either no function with this selector exists in the ` +
+        `contract, or the registered artifact does not match the class id (re-register it via ` +
+        `wallet.registerContract(...)).`,
+    );
+  }
+  return fn;
+}

package/src/storage/fact_store/fact_service.ts

@@ -0,0 +1,69 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+
+import { assertAllowedScope } from '../allowed_scopes.js';
+import type { FactStore } from './fact_store.js';
+import type { FactCollectionKey, FactCollectionTypeKey, OriginBlock } from './fact_store_keys.js';
+import {
+  type FactCollectionWithOriginState,
+  type FactWithOriginState,
+  type TipBlockNumbers,
+  toFactWithOriginState,
+} from './origin_state.js';
+import type { Fact } from './stored_fact.js';
+
+/**
+ * Wraps a {@link FactStore} with scope-based access control.
+ *
+ * Each method asserts scope validity before delegating to FactStore, gating which accounts a contract may record facts
+ * under or read facts from.
+ */
+export class FactService {
+  constructor(
+    private readonly factStore: FactStore,
+    private readonly allowedScopes: AztecAddress[],
+  ) {}
+
+  recordFact(
+    factCollectionKey: FactCollectionKey,
+    factTypeId: Fr,
+    payload: Fr[],
+    originBlock: OriginBlock | undefined,
+    jobId: string,
+  ): Promise<void> {
+    assertAllowedScope(factCollectionKey.scope, this.allowedScopes);
+    return this.factStore.recordFact(factCollectionKey, factTypeId, payload, originBlock, jobId);
+  }
+
+  deleteFactCollection(factCollectionKey: FactCollectionKey, jobId: string): Promise<void> {
+    assertAllowedScope(factCollectionKey.scope, this.allowedScopes);
+    return this.factStore.deleteFactCollection(factCollectionKey, jobId);
+  }
+
+  async getFactCollection(
+    factCollectionKey: FactCollectionKey,
+    tips: TipBlockNumbers,
+    jobId: string,
+  ): Promise<FactCollectionWithOriginState | undefined> {
+    assertAllowedScope(factCollectionKey.scope, this.allowedScopes);
+    const collection = await this.factStore.getFactCollection(factCollectionKey, jobId);
+    if (!collection) {
+      return undefined;
+    }
+    return { key: collection.key, facts: this.#annotate(collection.facts, tips) };
+  }
+
+  async getFactCollectionsByType(
+    factCollectionTypeKey: FactCollectionTypeKey,
+    tips: TipBlockNumbers,
+    jobId: string,
+  ): Promise<FactCollectionWithOriginState[]> {
+    assertAllowedScope(factCollectionTypeKey.scope, this.allowedScopes);
+    const collections = await this.factStore.getFactCollectionsByType(factCollectionTypeKey, jobId);
+    return collections.map(collection => ({ key: collection.key, facts: this.#annotate(collection.facts, tips) }));
+  }
+
+  #annotate(facts: Fact[], tips: TipBlockNumbers): FactWithOriginState[] {
+    return facts.map(fact => toFactWithOriginState(fact, tips));
+  }
+}