@aztec/pxe 5.0.0-rc.2 → 5.0.0

package/src/storage/backwards_compatibility_tests/__snapshots__/KeyStore.json

@@ -1,51 +1,51 @@
 {
   "key_store": [
     {
-      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-ivpk_m",
+      "key": "utf8:0x2369ead09116908cedc1642d5e0c714ef288ecbc838e4d434f800a408914ce44-ivpk_m",
       "value": "19e95c05f09cb86d1a6257572f9082ca15d4a02373c4d8c9cee23dc61a4c2a882f9017d51bca6616102d8a1d4dba89e4ce12881a2414576f01d2fec9492814a2"
     },
     {
-      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-ivpk_m_hash",
+      "key": "utf8:0x2369ead09116908cedc1642d5e0c714ef288ecbc838e4d434f800a408914ce44-ivpk_m_hash",
       "value": "1fd17152d394f6a43b527c531590888d610d1bcb9aa71a02498ce820bbf4dc62"
     },
     {
-      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-ivsk_m",
+      "key": "utf8:0x2369ead09116908cedc1642d5e0c714ef288ecbc838e4d434f800a408914ce44-ivsk_m",
       "value": "1fb01c42d1aaa2662041b899c77cb19e08192193acc5a94405f1b43c974eba7a"
     },
     {
-      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-nhk_m",
+      "key": "utf8:0x2369ead09116908cedc1642d5e0c714ef288ecbc838e4d434f800a408914ce44-nhk_m",
       "value": "2dd30220767969b10044b1322585bb4c4df4e0c5d9b4d7b3045a879a8e3e91d2"
     },
     {
-      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-npk_m",
+      "key": "utf8:0x2369ead09116908cedc1642d5e0c714ef288ecbc838e4d434f800a408914ce44-npk_m",
       "value": "214c7a24ddf501afc8734c7379ee502296289eb24cd8cd03cd435e128c06be0000987721e0963b4a5bd81ee862e2740d8849fd90537569064d3d3a4640e858d2"
     },
     {
-      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-npk_m_hash",
+      "key": "utf8:0x2369ead09116908cedc1642d5e0c714ef288ecbc838e4d434f800a408914ce44-npk_m_hash",
       "value": "13ad6965d11a533a663d07507319f74ac3305325f6f72423c0b24aa1193268bb"
     },
     {
-      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-ovpk_m",
+      "key": "utf8:0x2369ead09116908cedc1642d5e0c714ef288ecbc838e4d434f800a408914ce44-ovpk_m",
       "value": "2c19ff0b089b07da436e6f7be6b26cdc17b9cee504a528c071ef6a416299683d0b369479d6e50504702d0b56bb56e4e8e0e77171429896651d0c11621e82ebc3"
     },
     {
-      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-ovpk_m_hash",
+      "key": "utf8:0x2369ead09116908cedc1642d5e0c714ef288ecbc838e4d434f800a408914ce44-ovpk_m_hash",
       "value": "2a1b054e998835d166711839b515d434b1fbc207ad4fdb5b2b43d6ac6b400871"
     },
     {
-      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-ovsk_m",
+      "key": "utf8:0x2369ead09116908cedc1642d5e0c714ef288ecbc838e4d434f800a408914ce44-ovsk_m",
       "value": "279fe6ef7dd2477b919327b1ebab7497c41b9a7ccfa9d5d52e32698e3b85293b"
     },
     {
-      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-tpk_m",
+      "key": "utf8:0x2369ead09116908cedc1642d5e0c714ef288ecbc838e4d434f800a408914ce44-tpk_m",
       "value": "2fcdd0d194adafd753dc0ed279f5cfb54ddcce1dd581d4631cf343ba9ee6c1ab2858abca6c00da3def156b1f12a6464384e326d5fa724c2fc2ff2b7f3fc8ad5f"
     },
     {
-      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-tpk_m_hash",
+      "key": "utf8:0x2369ead09116908cedc1642d5e0c714ef288ecbc838e4d434f800a408914ce44-tpk_m_hash",
       "value": "019f5bb255e87523d43da83ebc9fa95169b653d4abef902e011e9eac620fc45b"
     },
     {
-      "key": "utf8:0x0b3683ee9df3ed6ed7027145bd6093f783b0bb4d8354501d906db7bb8cb58ea3-tsk_m",
+      "key": "utf8:0x2369ead09116908cedc1642d5e0c714ef288ecbc838e4d434f800a408914ce44-tsk_m",
       "value": "183cb61099458d1564aa57c90c7091ac623a14092ab314150c9cfbb416810320"
     }
   ]

package/src/storage/backwards_compatibility_tests/__snapshots__/RecipientTaggingStore.json

@@ -1,17 +1,25 @@
 {
   "highest_aged_index": [
     {
-      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000002:0x0000000000000000000000000000000000000000000000000000000000000003",
+      "key": "utf8:constrained:0x0000000000000000000000000000000000000000000000000000000000000013:0x0000000000000000000000000000000000000000000000000000000000000017",
+      "value": "num:13"
+    },
+    {
+      "key": "utf8:unconstrained:0x0000000000000000000000000000000000000000000000000000000000000002:0x0000000000000000000000000000000000000000000000000000000000000003",
       "value": "num:13"
     }
   ],
   "highest_finalized_index": [
     {
-      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000002:0x0000000000000000000000000000000000000000000000000000000000000003",
+      "key": "utf8:constrained:0x0000000000000000000000000000000000000000000000000000000000000013:0x0000000000000000000000000000000000000000000000000000000000000017",
+      "value": "num:11"
+    },
+    {
+      "key": "utf8:unconstrained:0x0000000000000000000000000000000000000000000000000000000000000002:0x0000000000000000000000000000000000000000000000000000000000000003",
       "value": "num:11"
     },
     {
-      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000005:0x0000000000000000000000000000000000000000000000000000000000000007",
+      "key": "utf8:unconstrained:0x0000000000000000000000000000000000000000000000000000000000000005:0x0000000000000000000000000000000000000000000000000000000000000007",
       "value": "num:17"
     }
   ]

package/src/storage/backwards_compatibility_tests/__snapshots__/SenderTaggingStore.json

@@ -1,21 +1,29 @@
 {
   "pending_indexes": [
     {
-      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000002:0x0000000000000000000000000000000000000000000000000000000000000003",
+      "key": "utf8:constrained:0x0000000000000000000000000000000000000000000000000000000000000013:0x0000000000000000000000000000000000000000000000000000000000000017",
+      "value": "[{\"lowestIndex\":4,\"highestIndex\":7,\"txHash\":\"0x0000000000000000000000000000000000000000000000000000000000000025\"}]"
+    },
+    {
+      "key": "utf8:unconstrained:0x0000000000000000000000000000000000000000000000000000000000000002:0x0000000000000000000000000000000000000000000000000000000000000003",
       "value": "[{\"lowestIndex\":4,\"highestIndex\":7,\"txHash\":\"0x0000000000000000000000000000000000000000000000000000000000000013\"},{\"lowestIndex\":8,\"highestIndex\":11,\"txHash\":\"0x0000000000000000000000000000000000000000000000000000000000000017\"}]"
     },
     {
-      "key": "utf8:0x000000000000000000000000000000000000000000000000000000000000000b:0x000000000000000000000000000000000000000000000000000000000000000d",
+      "key": "utf8:unconstrained:0x000000000000000000000000000000000000000000000000000000000000000b:0x000000000000000000000000000000000000000000000000000000000000000d",
       "value": "[{\"lowestIndex\":1,\"highestIndex\":9,\"txHash\":\"0x000000000000000000000000000000000000000000000000000000000000001d\"}]"
     }
   ],
   "last_finalized_indexes": [
     {
-      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000002:0x0000000000000000000000000000000000000000000000000000000000000003",
+      "key": "utf8:constrained:0x0000000000000000000000000000000000000000000000000000000000000013:0x0000000000000000000000000000000000000000000000000000000000000017",
+      "value": "num:3"
+    },
+    {
+      "key": "utf8:unconstrained:0x0000000000000000000000000000000000000000000000000000000000000002:0x0000000000000000000000000000000000000000000000000000000000000003",
       "value": "num:3"
     },
     {
-      "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000005:0x0000000000000000000000000000000000000000000000000000000000000007",
+      "key": "utf8:unconstrained:0x0000000000000000000000000000000000000000000000000000000000000005:0x0000000000000000000000000000000000000000000000000000000000000007",
       "value": "num:5"
     }
   ]

package/src/storage/backwards_compatibility_tests/__snapshots__/TaggingSecretSourcesStore.json

@@ -16,15 +16,15 @@
   "recipient_shared_secrets": [
     {
       "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000007",
-      "value": "utf8:0x00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000003"
+      "value": "{\"kind\":\"arbitrary-secret\",\"secret\":\"0x00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000003\"}"
     },
     {
       "key": "utf8:0x0000000000000000000000000000000000000000000000000000000000000007",
-      "value": "utf8:0x00000000000000000000000000000000000000000000000000000000000000050000000000000000000000000000000000000000000000000000000000000007"
+      "value": "{\"kind\":\"handshake\",\"secret\":\"0x00000000000000000000000000000000000000000000000000000000000000050000000000000000000000000000000000000000000000000000000000000007\"}"
     },
     {
       "key": "utf8:0x000000000000000000000000000000000000000000000000000000000000000b",
-      "value": "utf8:0x000000000000000000000000000000000000000000000000000000000000000d0000000000000000000000000000000000000000000000000000000000000011"
+      "value": "{\"kind\":\"arbitrary-secret\",\"secret\":\"0x000000000000000000000000000000000000000000000000000000000000000d0000000000000000000000000000000000000000000000000000000000000011\"}"
     }
   ]
 }

package/src/storage/backwards_compatibility_tests/__snapshots__/opened_stores.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 9,
+  "schemaVersion": 13,
   "stores": [
     {
       "name": "capsules",

package/src/storage/backwards_compatibility_tests/schema_tests.ts

@@ -15,9 +15,10 @@ import { BlockHash, Body, GENESIS_BLOCK_HEADER_HASH, L2Block } from '@aztec/stdl
 import { Checkpoint, L1PublishedData, PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
 import { CompleteAddress, SerializableContractInstance } from '@aztec/stdlib/contract';
 import { GasFees } from '@aztec/stdlib/gas';
-import { PublicKey, PublicKeys } from '@aztec/stdlib/keys';
+import { PublicKey, PublicKeys, deriveKeys } from '@aztec/stdlib/keys';
 import {
   AppTaggingSecret,
+  AppTaggingSecretKind,
   ContractClassLog,
   ContractClassLogFields,
   PrivateLog,
@@ -255,7 +256,7 @@ export const SCHEMA_TESTS: readonly SchemaTest[] = [
     name: 'KeyStore',
     writeToStore: async kvStore => {
       const keyStore = new KeyStore(kvStore);
-      await keyStore.addAccount(new Fr(2n), new Fr(3n));
+      await keyStore.addAccount(await deriveKeys(new Fr(2n)), new Fr(3n));
     },
     snapshotStore: async kvStore => ({
       key_store: await snapshotMap(kvStore.openMap<string, Buffer>('key_store')),
@@ -530,10 +531,18 @@ export const SCHEMA_TESTS: readonly SchemaTest[] = [
       const jobId = 'fixture-job';
       const secretA = new AppTaggingSecret(new Fr(2n), AztecAddress.fromBigIntUnsafe(3n));
       const secretB = new AppTaggingSecret(new Fr(5n), AztecAddress.fromBigIntUnsafe(7n));
+      // A constrained secret keys under the `constrained:` prefix, so the snapshot pins both kinds side by side.
+      const secretConstrained = new AppTaggingSecret(
+        new Fr(19n),
+        AztecAddress.fromBigIntUnsafe(23n),
+        AppTaggingSecretKind.CONSTRAINED,
+      );
 
       await recipientTaggingStore.updateHighestFinalizedIndex(secretA, 11, jobId);
       await recipientTaggingStore.updateHighestAgedIndex(secretA, 13, jobId);
       await recipientTaggingStore.updateHighestFinalizedIndex(secretB, 17, jobId);
+      await recipientTaggingStore.updateHighestFinalizedIndex(secretConstrained, 11, jobId);
+      await recipientTaggingStore.updateHighestAgedIndex(secretConstrained, 13, jobId);
       await kvStore.transactionAsync(() => recipientTaggingStore.commit(jobId));
     },
     snapshotStore: async kvStore => ({
@@ -553,20 +562,25 @@ export const SCHEMA_TESTS: readonly SchemaTest[] = [
 
       await taggingSecretSourcesStore.addSharedSecret(
         AztecAddress.fromBigIntUnsafe(7n),
+        'arbitrary-secret',
         new Point(new Fr(2n), new Fr(3n)),
       );
       await taggingSecretSourcesStore.addSharedSecret(
         AztecAddress.fromBigIntUnsafe(7n),
+        'handshake',
         new Point(new Fr(5n), new Fr(7n)),
       );
       await taggingSecretSourcesStore.addSharedSecret(
         AztecAddress.fromBigIntUnsafe(11n),
+        'arbitrary-secret',
         new Point(new Fr(13n), new Fr(17n)),
       );
     },
     snapshotStore: async kvStore => ({
       senders: await snapshotMap(kvStore.openMap<string, true>('senders')),
-      recipient_shared_secrets: await snapshotMap(kvStore.openMultiMap<string, string>('recipient_shared_secrets')),
+      recipient_shared_secrets: await snapshotMap(
+        kvStore.openMultiMap<string, { kind: string; secret: string }>('recipient_shared_secrets'),
+      ),
     }),
   },
 
@@ -579,10 +593,17 @@ export const SCHEMA_TESTS: readonly SchemaTest[] = [
       const secretA = new AppTaggingSecret(new Fr(2n), AztecAddress.fromBigIntUnsafe(3n));
       const secretB = new AppTaggingSecret(new Fr(5n), AztecAddress.fromBigIntUnsafe(7n));
       const secretC = new AppTaggingSecret(new Fr(11n), AztecAddress.fromBigIntUnsafe(13n));
+      const secretConstrained = new AppTaggingSecret(
+        new Fr(19n),
+        AztecAddress.fromBigIntUnsafe(23n),
+        AppTaggingSecretKind.CONSTRAINED,
+      );
       const txHashA = TxHash.fromBigInt(17n);
       const txHashB = TxHash.fromBigInt(19n);
       const txHashC = TxHash.fromBigInt(23n);
       const txHashD = TxHash.fromBigInt(29n);
+      const txHashE = TxHash.fromBigInt(31n);
+      const txHashF = TxHash.fromBigInt(37n);
 
       // secretA receives three pending ranges (one per tx); secretB receives one. After finalizing txHashA below,
       // secretA's array shrinks to two elements (the txHashB and txHashC ranges, both with highestIndex > 3) which
@@ -621,7 +642,20 @@ export const SCHEMA_TESTS: readonly SchemaTest[] = [
         jobId,
       );
 
-      await senderTaggingStore.finalizePendingIndexes([txHashA], jobId);
+      // secretConstrained gets a finalized range (txHashE) plus a surviving higher pending range (txHashF), so the
+      // `constrained:` key lands in both pending_indexes and last_finalized_indexes.
+      await senderTaggingStore.storePendingIndexes(
+        [{ extendedSecret: secretConstrained, lowestIndex: 1, highestIndex: 3 }],
+        txHashE,
+        jobId,
+      );
+      await senderTaggingStore.storePendingIndexes(
+        [{ extendedSecret: secretConstrained, lowestIndex: 4, highestIndex: 7 }],
+        txHashF,
+        jobId,
+      );
+
+      await senderTaggingStore.finalizePendingIndexes([txHashA, txHashE], jobId);
 
       await kvStore.transactionAsync(() => senderTaggingStore.commit(jobId));
     },

package/src/storage/contract_store/contract_store.ts

@@ -6,7 +6,6 @@ import type { MembershipWitness } from '@aztec/foundation/trees';
 import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
 import {
   type ContractArtifact,
-  type FunctionAbi,
   type FunctionArtifactWithContractName,
   FunctionCall,
   type FunctionDebugMetadata,
@@ -23,8 +22,8 @@ import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import {
   type ContractClassIdPreimage,
   type ContractClassWithId,
-  type ContractInstanceWithAddress,
-  SerializableContractInstance,
+  type ContractInstancePreimageWithAddress,
+  SerializableContractInstancePreimage,
   getContractClassFromArtifact,
 } from '@aztec/stdlib/contract';
 
@@ -112,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>;
@@ -131,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,
@@ -168,31 +165,17 @@ export class ContractStore {
     return contractClass.id;
   }
 
-  async addContractInstance(contract: ContractInstanceWithAddress): Promise<void> {
+  async addContractInstance(contract: ContractInstancePreimageWithAddress): Promise<void> {
     await this.#store.transactionAsync(async () => {
       await this.#contractInstances.set(
         contract.address.toString(),
-        new SerializableContractInstance(contract).toBuffer(),
+        new SerializableContractInstancePreimage(contract).toBuffer(),
       );
     });
-
-    this.#contractClassIdMap.set(contract.address.toString(), contract.currentContractClassId);
   }
 
   // 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);
@@ -205,11 +188,6 @@ 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[]> {
@@ -219,11 +197,11 @@ export class ContractStore {
     });
   }
 
-  /** 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);
     });
   }
 
@@ -262,82 +240,69 @@ 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 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 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;
     }
@@ -345,10 +310,8 @@ export class ContractStore {
     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);
   }
@@ -368,28 +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);
+  public async getDebugFunctionName(contractClassId: Fr, selector: FunctionSelector) {
+    const artifact = await this.getContractArtifact(contractClassId);
     const fn = artifact && (await findFunctionAbiBySelector(artifact, selector));
-    return `${artifact?.name ?? contractAddress}:${fn?.name ?? 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}: register it by calling wallet.registerContract(...).\nSee docs for context: https://docs.aztec.network/errors/14`,
+        `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);
@@ -406,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

@@ -2,8 +2,15 @@ import type { Fr } from '@aztec/foundation/curves/bn254';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 
 import { assertAllowedScope } from '../allowed_scopes.js';
-import type { FactCollection, FactStore } from './fact_store.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.
@@ -33,13 +40,30 @@ export class FactService {
     return this.factStore.deleteFactCollection(factCollectionKey, jobId);
   }
 
-  getFactCollection(factCollectionKey: FactCollectionKey, jobId: string): Promise<FactCollection | undefined> {
+  async getFactCollection(
+    factCollectionKey: FactCollectionKey,
+    tips: TipBlockNumbers,
+    jobId: string,
+  ): Promise<FactCollectionWithOriginState | undefined> {
     assertAllowedScope(factCollectionKey.scope, this.allowedScopes);
-    return this.factStore.getFactCollection(factCollectionKey, jobId);
+    const collection = await this.factStore.getFactCollection(factCollectionKey, jobId);
+    if (!collection) {
+      return undefined;
+    }
+    return { key: collection.key, facts: this.#annotate(collection.facts, tips) };
   }
 
-  getFactCollectionsByType(factCollectionTypeKey: FactCollectionTypeKey, jobId: string): Promise<FactCollection[]> {
+  async getFactCollectionsByType(
+    factCollectionTypeKey: FactCollectionTypeKey,
+    tips: TipBlockNumbers,
+    jobId: string,
+  ): Promise<FactCollectionWithOriginState[]> {
     assertAllowedScope(factCollectionTypeKey.scope, this.allowedScopes);
-    return this.factStore.getFactCollectionsByType(factCollectionTypeKey, jobId);
+    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));
   }
 }

package/src/storage/fact_store/fact_store.ts

@@ -82,7 +82,7 @@ export class FactStore implements StagedStore {
   }
 
   /**
-   * Records a fact in a collection.
+   * Records a fact in a collection, visible under the given scope.
    *
    * The collection is created implicitly on the first fact recorded for its key: recording into an existing collection
    * just adds to it.

package/src/storage/fact_store/index.ts

@@ -2,3 +2,13 @@ export { FactStore, type FactCollection } from './fact_store.js';
 export { FactService } from './fact_service.js';
 export { FactCollectionKey, FactCollectionTypeKey, type OriginBlock } from './fact_store_keys.js';
 export type { Fact } from './stored_fact.js';
+export {
+  OriginBlockState,
+  classifyOriginBlockState,
+  anchoredTipBlockNumbers,
+  toFactWithOriginState,
+  type TipBlockNumbers,
+  type RetractableFactOrigin,
+  type FactWithOriginState,
+  type FactCollectionWithOriginState,
+} from './origin_state.js';