@aztec-labs/pxe 6.0.0-nightly.20260829

package/src/storage/store_identity.ts

@@ -0,0 +1,72 @@
+import type { EthAddress } from '@aztec-labs/foundation/eth-address';
+import type { AztecAsyncKVStore } from '@aztec-labs/kv-store';
+import { DatabaseVersion } from '@aztec-labs/stdlib/database-version/version';
+
+/** The triple that determine which physical store a logical store name maps to. */
+export type StoreIdentity = {
+  /** Chain ID of the L1 the rollup is deployed to. */
+  l1ChainId: number;
+  /** Address of the rollup contract the store's data pertains to. */
+  rollupAddress: EthAddress;
+  /** Schema version of the data held in the store. */
+  schemaVersion: number;
+};
+
+/**
+ * Composes the store-name discriminator for a store identity. Two identities map to the same physical store iff
+ * their slugs are equal, so the format must stay stable: `<l1ChainId>-<rollupAddress>-v<schemaVersion>` — changing
+ * it orphans every existing store.
+ */
+export function storeIdentitySlug({ l1ChainId, rollupAddress, schemaVersion }: StoreIdentity): string {
+  return `${l1ChainId}-${rollupAddress.toString()}-v${schemaVersion}`;
+}
+
+/** Composes the physical store name for a logical store name and identity. */
+export function effectiveStoreName(name: string, identity: StoreIdentity): string {
+  return `${name}_${storeIdentitySlug(identity)}`;
+}
+
+/**
+ * Invariant check for stores whose physical name carries their identity: the recorded version can
+ * only disagree with the expected one if there is a store-naming bug.
+ */
+export async function assertStoreIdentity(
+  store: AztecAsyncKVStore,
+  storeName: string,
+  identity: StoreIdentity,
+): Promise<void> {
+  const expected = new DatabaseVersion(identity.schemaVersion, identity.rollupAddress);
+  const singleton = store.openSingleton<string>('dbVersion');
+  const stored = await singleton.getAsync();
+  if (stored === undefined) {
+    await singleton.set(expected.toBuffer().toString('utf-8'));
+    return;
+  }
+  let storedVersion: DatabaseVersion;
+  try {
+    storedVersion = DatabaseVersion.fromBuffer(Buffer.from(stored, 'utf-8'));
+  } catch {
+    throw new StoreIdentityMismatchError(storeName, expected.toString(), stored);
+  }
+  if (!storedVersion.equals(expected)) {
+    throw new StoreIdentityMismatchError(storeName, expected.toString(), storedVersion.toString());
+  }
+}
+
+/**
+ * Thrown when a store's recorded identity does not match the identity it was opened under. Since the identity is
+ * part of the physical store name, this can only indicate a store-naming bug; the store is left untouched.
+ */
+export class StoreIdentityMismatchError extends Error {
+  constructor(
+    public readonly storeName: string,
+    public readonly expected: string,
+    public readonly actual: string,
+  ) {
+    super(
+      `Store '${storeName}' records identity ${actual} but was opened as ${expected}. ` +
+        `Refusing to open; data was NOT modified.`,
+    );
+    this.name = 'StoreIdentityMismatchError';
+  }
+}

package/src/storage/tagging_store/index.ts

@@ -0,0 +1,3 @@
+export { SenderTaggingStore } from './sender_tagging_store.js';
+export { TaggingSecretSourcesStore } from './tagging_secret_sources_store.js';
+export { RecipientTaggingStore } from './recipient_tagging_store.js';

package/src/storage/tagging_store/recipient_tagging_store.ts

@@ -0,0 +1,114 @@
+import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec-labs/kv-store';
+import type { AppTaggingSecret } from '@aztec-labs/stdlib/logs';
+
+import { BaseStagingStore, type ReadonlyDb } from '../base_staging_store.js';
+import type { ChangeSetId } from '../staged_write_coordinator.js';
+
+/**
+ * Data provider of tagging data used when syncing the logs as a recipient. The sender counterpart of this class
+ * is called SenderTaggingStore. We have the providers separate for the sender and recipient because
+ * the algorithms are completely disjoint and there is not data reuse between the two.
+ *
+ * @dev Chain reorgs do not need to be handled here because both the finalized and aged indexes refer to finalized
+ * blocks, which by definition cannot be affected by reorgs.
+ */
+export class RecipientTaggingStore extends BaseStagingStore<RecipientTaggingChangeSet, RecipientTaggingDb> {
+  constructor(store: AztecAsyncKVStore) {
+    super({
+      storeName: 'recipient_tagging',
+      store,
+      buildChangeSet: () => ({ highestAgedIndexes: new Map(), highestFinalizedIndexes: new Map() }),
+      buildDb: db => ({
+        highestAgedIndex: db.openMap('highest_aged_index'),
+        highestFinalizedIndex: db.openMap('highest_finalized_index'),
+      }),
+    });
+  }
+
+  async #readHighestAgedIndex(
+    changeSet: RecipientTaggingChangeSet,
+    db: ReadonlyDb<RecipientTaggingDb>,
+    secret: SecretStr,
+  ): Promise<Index | undefined> {
+    // Always issue DB read to keep IndexedDB transaction alive (they auto-commit when a new micro-task starts and there
+    // are no pending read requests). The staged value still takes precedence if it exists.
+    const dbValue = await db.highestAgedIndex.getAsync(secret);
+    return changeSet.highestAgedIndexes.get(secret) ?? dbValue;
+  }
+
+  async #readHighestFinalizedIndex(
+    changeSet: RecipientTaggingChangeSet,
+    db: ReadonlyDb<RecipientTaggingDb>,
+    secret: SecretStr,
+  ): Promise<Index | undefined> {
+    // Always issue DB read to keep IndexedDB transaction alive (they auto-commit when a new micro-task starts and there
+    // are no pending read requests). The staged value still takes precedence if it exists.
+    const dbValue = await db.highestFinalizedIndex.getAsync(secret);
+    return changeSet.highestFinalizedIndexes.get(secret) ?? dbValue;
+  }
+
+  protected async flushChangeSet(changeSet: RecipientTaggingChangeSet, db: RecipientTaggingDb): Promise<void> {
+    for (const [secret, index] of changeSet.highestAgedIndexes) {
+      await db.highestAgedIndex.set(secret, index);
+    }
+
+    for (const [secret, index] of changeSet.highestFinalizedIndexes) {
+      await db.highestFinalizedIndex.set(secret, index);
+    }
+  }
+
+  /** No-op: both indexes refer to finalized blocks, which a prune cannot remove. */
+  protected applyRollback(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  getHighestAgedIndex(secret: AppTaggingSecret, changeSetId: ChangeSetId): Promise<Index | undefined> {
+    return this.withChangeSetAndDb(changeSetId, (changeSet, db) =>
+      this.#readHighestAgedIndex(changeSet, db, secret.toString()),
+    );
+  }
+
+  updateHighestAgedIndex(secret: AppTaggingSecret, index: Index, changeSetId: ChangeSetId): Promise<void> {
+    return this.withChangeSetAndDb(changeSetId, async (changeSet, db) => {
+      const currentIndex = await this.#readHighestAgedIndex(changeSet, db, secret.toString());
+      if (currentIndex !== undefined && index <= currentIndex) {
+        // Log sync should never set a lower highest aged index.
+        throw new Error(`New highest aged index (${index}) must be higher than the current one (${currentIndex})`);
+      }
+      changeSet.highestAgedIndexes.set(secret.toString(), index);
+    });
+  }
+
+  getHighestFinalizedIndex(secret: AppTaggingSecret, changeSetId: ChangeSetId): Promise<Index | undefined> {
+    return this.withChangeSetAndDb(changeSetId, (changeSet, db) =>
+      this.#readHighestFinalizedIndex(changeSet, db, secret.toString()),
+    );
+  }
+
+  updateHighestFinalizedIndex(secret: AppTaggingSecret, index: Index, changeSetId: ChangeSetId): Promise<void> {
+    return this.withChangeSetAndDb(changeSetId, async (changeSet, db) => {
+      const currentIndex = await this.#readHighestFinalizedIndex(changeSet, db, secret.toString());
+      if (currentIndex !== undefined && index < currentIndex) {
+        // Log sync should never set a lower highest finalized index but it can happen that it would try to set the same
+        // one because we are loading logs from highest aged index + 1 and not from the highest finalized index.
+        throw new Error(`New highest finalized index (${index}) must be higher than the current one (${currentIndex})`);
+      }
+      changeSet.highestFinalizedIndexes.set(secret.toString(), index);
+    });
+  }
+}
+
+/// Alias types for kv map readability
+type SecretStr = string;
+type Index = number;
+
+/** A change set's staged data, created and discarded as a unit: both indexes, each keyed by tagging secret. */
+type RecipientTaggingChangeSet = {
+  highestAgedIndexes: Map<SecretStr, Index>;
+  highestFinalizedIndexes: Map<SecretStr, Index>;
+};
+
+type RecipientTaggingDb = {
+  highestAgedIndex: AztecAsyncMap<SecretStr, Index>;
+  highestFinalizedIndex: AztecAsyncMap<SecretStr, Index>;
+};