@aztec/pxe 0.0.1-commit.2448fdb → 0.0.1-commit.2606882

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/contract_store/contract_store.ts

@@ -7,7 +7,6 @@ import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
 import {
   type ContractArtifact,
   type FunctionAbi,
-  type FunctionArtifact,
   type FunctionArtifactWithContractName,
   FunctionCall,
   type FunctionDebugMetadata,
@@ -16,6 +15,8 @@ import {
   contractArtifactFromBuffer,
   contractArtifactToBuffer,
   encodeArguments,
+  findFunctionAbiBySelector,
+  findFunctionArtifactBySelector,
   getFunctionDebugMetadata,
 } from '@aztec/stdlib/abi';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
@@ -290,7 +291,7 @@ export class ContractStore {
     if (!artifact) {
       return undefined;
     }
-    const fn = await this.#findFunctionArtifactBySelector(artifact, selector);
+    const fn = await findFunctionArtifactBySelector(artifact, selector);
     return fn && { ...fn, contractName: artifact.name };
   }
 
@@ -322,7 +323,7 @@ export class ContractStore {
     selector: FunctionSelector,
   ): Promise<FunctionAbi | undefined> {
     const artifact = await this.#getArtifactByAddress(contractAddress);
-    return artifact && (await this.#findFunctionAbiBySelector(artifact, selector));
+    return artifact && (await findFunctionAbiBySelector(artifact, selector));
   }
 
   /**
@@ -340,7 +341,7 @@ export class ContractStore {
     if (!artifact) {
       return undefined;
     }
-    const fn = await this.#findFunctionArtifactBySelector(artifact, selector);
+    const fn = await findFunctionArtifactBySelector(artifact, selector);
     return fn && getFunctionDebugMetadata(artifact, fn);
   }
 
@@ -374,34 +375,10 @@ export class ContractStore {
 
   public async getDebugFunctionName(contractAddress: AztecAddress, selector: FunctionSelector) {
     const artifact = await this.#getArtifactByAddress(contractAddress);
-    const fn = artifact && (await this.#findFunctionAbiBySelector(artifact, selector));
+    const fn = artifact && (await 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 getFunctionCall(functionName: string, args: any[], to: AztecAddress): Promise<FunctionCall> {
     const contract = await this.getContract(to);
     if (!contract) {

package/src/storage/metadata.ts

@@ -1 +1 @@
-export const PXE_DATA_SCHEMA_VERSION = 5;
+export const PXE_DATA_SCHEMA_VERSION = 6;

package/src/storage/open_pxe_stores.ts

@@ -0,0 +1,49 @@
+import { KeyStore } from '@aztec/key-store';
+import type { AztecAsyncKVStore } from '@aztec/kv-store';
+import { L2TipsKVStore } from '@aztec/kv-store/stores';
+import type { BlockHash } from '@aztec/stdlib/block';
+
+import { AddressStore } from './address_store/address_store.js';
+import { AnchorBlockStore } from './anchor_block_store/anchor_block_store.js';
+import { CapsuleStore } from './capsule_store/capsule_store.js';
+import { ContractStore } from './contract_store/contract_store.js';
+import { NoteStore } from './note_store/note_store.js';
+import { PrivateEventStore } from './private_event_store/private_event_store.js';
+import { RecipientTaggingStore, SenderAddressBookStore, SenderTaggingStore } from './tagging_store/index.js';
+
+/**
+ * The set of sub-stores opened against a single `AztecAsyncKVStore` to back PXE state.
+ */
+export type PxeStores = {
+  addressStore: AddressStore;
+  privateEventStore: PrivateEventStore;
+  contractStore: ContractStore;
+  noteStore: NoteStore;
+  anchorBlockStore: AnchorBlockStore;
+  senderTaggingStore: SenderTaggingStore;
+  senderAddressBookStore: SenderAddressBookStore;
+  recipientTaggingStore: RecipientTaggingStore;
+  capsuleStore: CapsuleStore;
+  keyStore: KeyStore;
+  l2TipsStore: L2TipsKVStore;
+};
+
+/**
+ * Opens every PXE sub-store against the given backing store. The `initialBlockHash` seeds the
+ * `L2TipsKVStore` so it agrees with the node's archiver on the dynamic genesis header hash.
+ */
+export function openPxeStores(store: AztecAsyncKVStore, initialBlockHash: BlockHash): PxeStores {
+  return {
+    addressStore: new AddressStore(store),
+    privateEventStore: new PrivateEventStore(store),
+    contractStore: new ContractStore(store),
+    noteStore: new NoteStore(store),
+    anchorBlockStore: new AnchorBlockStore(store),
+    senderTaggingStore: new SenderTaggingStore(store),
+    senderAddressBookStore: new SenderAddressBookStore(store),
+    recipientTaggingStore: new RecipientTaggingStore(store),
+    capsuleStore: new CapsuleStore(store),
+    keyStore: new KeyStore(store),
+    l2TipsStore: new L2TipsKVStore(store, 'pxe', initialBlockHash),
+  };
+}

package/src/storage/private_event_store/stored_private_event.ts

@@ -49,7 +49,7 @@ export class StoredPrivateEvent {
     const msgContentLength = reader.readNumber();
     const msgContent = reader.readArray(msgContentLength, Fr);
     const l2BlockNumber = reader.readNumber();
-    const l2BlockHash = new BlockHash(Fr.fromBuffer(reader));
+    const l2BlockHash = BlockHash.fromBuffer(reader);
     const txHash = TxHash.fromBuffer(reader);
     const txIndexInBlock = reader.readNumber();
     const eventIndexInTx = reader.readNumber();

package/src/storage/tagging_store/recipient_tagging_store.ts

@@ -1,5 +1,5 @@
 import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
-import type { ExtendedDirectionalAppTaggingSecret } from '@aztec/stdlib/logs';
+import type { AppTaggingSecret } from '@aztec/stdlib/logs';
 
 import type { StagedStore } from '../../job_coordinator/job_coordinator.js';
 
@@ -106,11 +106,11 @@ export class RecipientTaggingStore implements StagedStore {
     return Promise.resolve();
   }
 
-  getHighestAgedIndex(secret: ExtendedDirectionalAppTaggingSecret, jobId: string): Promise<number | undefined> {
+  getHighestAgedIndex(secret: AppTaggingSecret, jobId: string): Promise<number | undefined> {
     return this.#store.transactionAsync(() => this.#readHighestAgedIndex(jobId, secret.toString()));
   }
 
-  updateHighestAgedIndex(secret: ExtendedDirectionalAppTaggingSecret, index: number, jobId: string): Promise<void> {
+  updateHighestAgedIndex(secret: AppTaggingSecret, index: number, jobId: string): Promise<void> {
     return this.#store.transactionAsync(async () => {
       const currentIndex = await this.#readHighestAgedIndex(jobId, secret.toString());
       if (currentIndex !== undefined && index <= currentIndex) {
@@ -121,15 +121,11 @@ export class RecipientTaggingStore implements StagedStore {
     });
   }
 
-  getHighestFinalizedIndex(secret: ExtendedDirectionalAppTaggingSecret, jobId: string): Promise<number | undefined> {
+  getHighestFinalizedIndex(secret: AppTaggingSecret, jobId: string): Promise<number | undefined> {
     return this.#store.transactionAsync(() => this.#readHighestFinalizedIndex(jobId, secret.toString()));
   }
 
-  updateHighestFinalizedIndex(
-    secret: ExtendedDirectionalAppTaggingSecret,
-    index: number,
-    jobId: string,
-  ): Promise<void> {
+  updateHighestFinalizedIndex(secret: AppTaggingSecret, index: number, jobId: string): Promise<void> {
     return this.#store.transactionAsync(async () => {
       const currentIndex = await this.#readHighestFinalizedIndex(jobId, secret.toString());
       if (currentIndex !== undefined && index < currentIndex) {

package/src/storage/tagging_store/sender_tagging_store.ts

@@ -1,5 +1,5 @@
 import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
-import { ExtendedDirectionalAppTaggingSecret, SiloedTag, type TaggingIndexRange } from '@aztec/stdlib/logs';
+import { AppTaggingSecret, SiloedTag, type TaggingIndexRange } from '@aztec/stdlib/logs';
 import { TxEffect, TxHash } from '@aztec/stdlib/tx';
 
 import type { StagedStore } from '../../job_coordinator/job_coordinator.js';
@@ -218,7 +218,7 @@ export class SenderTaggingStore implements StagedStore {
    * [startIndex, endIndex). Returns an empty array if no pending indexes exist in the range.
    */
   getTxHashesOfPendingIndexes(
-    secret: ExtendedDirectionalAppTaggingSecret,
+    secret: AppTaggingSecret,
     startIndex: number,
     endIndex: number,
     jobId: string,
@@ -237,7 +237,7 @@ export class SenderTaggingStore implements StagedStore {
    * @param secret - The secret to get the last finalized index for.
    * @returns The last (highest) finalized index for the given secret.
    */
-  getLastFinalizedIndex(secret: ExtendedDirectionalAppTaggingSecret, jobId: string): Promise<number | undefined> {
+  getLastFinalizedIndex(secret: AppTaggingSecret, jobId: string): Promise<number | undefined> {
     return this.#store.transactionAsync(() => this.#readLastFinalizedIndex(jobId, secret.toString()));
   }
 
@@ -247,7 +247,7 @@ export class SenderTaggingStore implements StagedStore {
    * @param secret - The directional app tagging secret to query the last used index for.
    * @returns The last used index.
    */
-  getLastUsedIndex(secret: ExtendedDirectionalAppTaggingSecret, jobId: string): Promise<number | undefined> {
+  getLastUsedIndex(secret: AppTaggingSecret, jobId: string): Promise<number | undefined> {
     const secretStr = secret.toString();
 
     return this.#store.transactionAsync(async () => {
@@ -449,11 +449,11 @@ export class SenderTaggingStore implements StagedStore {
       const pendingEntry = matchingEntries[0];
 
       // Expand each matching entry's range and recompute siloed tags for each index.
-      const extendedSecret = ExtendedDirectionalAppTaggingSecret.fromString(secret);
+      const appTaggingSecret = AppTaggingSecret.fromString(secret);
       let highestSurvivingIndex: number | undefined;
 
       for (let index = pendingEntry.lowestIndex; index <= pendingEntry.highestIndex; index++) {
-        const siloedTag = await SiloedTag.compute({ extendedSecret, index });
+        const siloedTag = await SiloedTag.compute({ extendedSecret: appTaggingSecret, index });
         if (onChainTags.has(siloedTag.value.toString())) {
           highestSurvivingIndex = highestSurvivingIndex !== undefined ? Math.max(highestSurvivingIndex, index) : index;
         }

package/src/tagging/get_all_logs_by_tags.ts

@@ -1,49 +1,54 @@
+import type { BlockNumber } from '@aztec/foundation/branded-types';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 import type { BlockHash } from '@aztec/stdlib/block';
-import { MAX_LOGS_PER_TAG, MAX_RPC_LEN } from '@aztec/stdlib/interfaces/api-limit';
+import { MAX_RPC_LEN } from '@aztec/stdlib/interfaces/api-limit';
 import type { AztecNode } from '@aztec/stdlib/interfaces/client';
-import type { SiloedTag, Tag, TxScopedL2Log } from '@aztec/stdlib/logs';
+import {
+  type LogIncludeOptions,
+  type LogResult,
+  type SiloedTag,
+  type Tag,
+  queryAllPrivateLogsByTags,
+  queryAllPublicLogsByTags,
+} from '@aztec/stdlib/logs';
+
+/** Optional block-range, effects opt-in, and pagination cap shared by both wrappers. */
+export type GetAllLogsByTagsOptions = {
+  /** Lower block bound, inclusive. */
+  fromBlock?: BlockNumber;
+  /** Upper block bound, exclusive. */
+  toBlock?: BlockNumber;
+  /**
+   * When set, each log also carries `noteHashes` and all `nullifiers` of its tx. Defaults to off — sender
+   * sync only needs `txHash`. The recipient-sync/log-service paths flip this on to build `PendingTaggedLog`
+   * / `LogRetrievalResponse` from note data.
+   */
+  includeEffects?: boolean;
+  /**
+   * Maximum number of logs returned per tag per round-trip. Capped at `MAX_LOGS_PER_TAG` on the node
+   * (rejected if higher). Defaults to `MAX_LOGS_PER_TAG`. Mainly useful for tests that need to force
+   * pagination at a small page size.
+   */
+  limitPerTag?: number;
+};
 
 /**
- * Generic pagination helper that fetches all pages of results.
- * @param numTags - The number of tags being queried (determines result array size).
- * @param fetchPage - Function that fetches a single page of results given a page number.
- * @returns An array of arrays, one per tag, containing all results across all pages.
+ * Splits tags into chunks of MAX_RPC_LEN, paginates each chunk via the stdlib per-tag cursor helper,
+ * then stitches the results back into a single array preserving the original tag order.
  */
-async function getAllPages<T>(numTags: number, fetchPage: (page: number) => Promise<T[][]>): Promise<T[][]> {
-  const allResultsPerTag: T[][] = Array.from({ length: numTags }, () => []);
-  let page = 0;
-  let hasMore = true;
-
-  while (hasMore) {
-    const resultsPage = await fetchPage(page);
-    hasMore = false;
-
-    for (let i = 0; i < resultsPage.length; i++) {
-      allResultsPerTag[i].push(...resultsPage[i]);
-      if (resultsPage[i].length === MAX_LOGS_PER_TAG) {
-        hasMore = true;
-      }
-    }
-    page++;
+async function getAllPagesInBatches<T extends Tag | SiloedTag, Opts extends LogIncludeOptions>(
+  tags: T[],
+  fetchAllPagesForBatch: (batch: T[]) => Promise<LogResult<Opts>[][]>,
+): Promise<LogResult<Opts>[][]> {
+  if (tags.length === 0) {
+    return [];
   }
 
-  return allResultsPerTag;
-}
-
-/**
- * Splits tags into chunks of MAX_RPC_LEN, fetches logs for each chunk using getAllPages, then stitches the results
- * back into a single array preserving the original tag order.
- */
-async function getAllPagesInBatches<Tag, T>(
-  tags: Tag[],
-  fetchAllPagesForBatch: (batch: Tag[]) => Promise<T[][]>,
-): Promise<T[][]> {
   if (tags.length <= MAX_RPC_LEN) {
     return fetchAllPagesForBatch(tags);
   }
 
-  const batches: Tag[][] = [];
+  const batches: T[][] = [];
   for (let i = 0; i < tags.length; i += MAX_RPC_LEN) {
     batches.push(tags.slice(i, i + MAX_RPC_LEN));
   }
@@ -52,41 +57,64 @@ async function getAllPagesInBatches<Tag, T>(
 }
 
 /**
- * Fetches all private logs for the given tags, automatically paginating through all pages.
+ * Fetches all private logs for the given tags, automatically paginating per-tag via `afterLog` cursors.
+ *
  * @param aztecNode - The Aztec node to query.
  * @param tags - The siloed tags to search for.
- * @param anchorBlockHash - reference block for the Aztec node query, throws if block is not found there (typically
- * because of reorgs).
+ * @param anchorBlockHash - Reference block for the Aztec node query, throws if block is not found there (typically
+ *   because of reorgs).
+ * @param options - Optional `fromBlock`/`toBlock` range and `includeEffects` opt-in.
  * @returns An array of log arrays, one per tag, containing all logs across all pages.
  */
-export function getAllPrivateLogsByTags(
+export function getAllPrivateLogsByTags<Opts extends GetAllLogsByTagsOptions = GetAllLogsByTagsOptions>(
   aztecNode: AztecNode,
   tags: SiloedTag[],
   anchorBlockHash: BlockHash,
-): Promise<TxScopedL2Log[][]> {
-  return getAllPagesInBatches(tags, batch =>
-    getAllPages(batch.length, page => aztecNode.getPrivateLogsByTags(batch, page, anchorBlockHash)),
+  options: Opts = {} as Opts,
+): Promise<LogResult<Opts>[][]> {
+  return getAllPagesInBatches<SiloedTag, Opts>(
+    tags,
+    batch =>
+      queryAllPrivateLogsByTags(aztecNode, {
+        tags: batch,
+        referenceBlock: anchorBlockHash,
+        fromBlock: options.fromBlock,
+        toBlock: options.toBlock,
+        includeEffects: options.includeEffects ?? false,
+        limitPerTag: options.limitPerTag,
+      }) as Promise<LogResult<Opts>[][]>,
   );
 }
 
 /**
- * Fetches all public logs for the given tags from a contract, automatically paginating through all pages.
+ * Fetches all public logs for the given tags from a contract, automatically paginating per-tag via `afterLog` cursors.
+ *
  * @param aztecNode - The Aztec node to query.
  * @param contractAddress - The contract address to search logs for.
  * @param tags - The tags to search for.
- * @param anchorBlockHash - reference block for the Aztec node query, throws if block is not found there (typically
- * because of reorgs).
+ * @param anchorBlockHash - Reference block for the Aztec node query, throws if block is not found there (typically
+ *   because of reorgs).
+ * @param options - Optional `fromBlock`/`toBlock` range and `includeEffects` opt-in.
  * @returns An array of log arrays, one per tag, containing all logs across all pages.
  */
-export function getAllPublicLogsByTagsFromContract(
+export function getAllPublicLogsByTagsFromContract<Opts extends GetAllLogsByTagsOptions = GetAllLogsByTagsOptions>(
   aztecNode: AztecNode,
   contractAddress: AztecAddress,
   tags: Tag[],
   anchorBlockHash: BlockHash,
-): Promise<TxScopedL2Log[][]> {
-  return getAllPagesInBatches(tags, batch =>
-    getAllPages(batch.length, page =>
-      aztecNode.getPublicLogsByTagsFromContract(contractAddress, batch, page, anchorBlockHash),
-    ),
+  options: Opts = {} as Opts,
+): Promise<LogResult<Opts>[][]> {
+  return getAllPagesInBatches<Tag, Opts>(
+    tags,
+    batch =>
+      queryAllPublicLogsByTags(aztecNode, {
+        contractAddress,
+        tags: batch,
+        referenceBlock: anchorBlockHash,
+        fromBlock: options.fromBlock,
+        toBlock: options.toBlock,
+        includeEffects: options.includeEffects ?? false,
+        limitPerTag: options.limitPerTag,
+      }) as Promise<LogResult<Opts>[][]>,
   );
 }

package/src/tagging/index.ts

@@ -4,16 +4,17 @@
  * The objective of the sender sync algorithm is to determine which tags have already been used by a sender, thereby
  * deciding which tag should be used next.
  *
- * The objective of the recipient sync algorithm is to load and process the corresponding logs.
+ * The objective of the recipient sync algorithm is to fetch and sync the corresponding logs.
  *
  * @module tagging
  */
 
-export { loadPrivateLogsForSenderRecipientPair } from './recipient_sync/load_private_logs_for_sender_recipient_pair.js';
+export { syncTaggedPrivateLogs } from './recipient_sync/sync_tagged_private_logs.js';
 export { syncSenderTaggingIndexes } from './sender_sync/sync_sender_tagging_indexes.js';
+export { persistSenderTaggingIndexRangesForTx } from './persist_sender_tagging_index_ranges.js';
 export { UNFINALIZED_TAGGING_INDEXES_WINDOW_LEN } from './constants.js';
 export { getAllPrivateLogsByTags, getAllPublicLogsByTagsFromContract } from './get_all_logs_by_tags.js';
 
 // Re-export tagging-related types from stdlib
-export { ExtendedDirectionalAppTaggingSecret, Tag, SiloedTag } from '@aztec/stdlib/logs';
+export { AppTaggingSecret, Tag, SiloedTag } from '@aztec/stdlib/logs';
 export { type PreTag, type TaggingIndexRange } from '@aztec/stdlib/logs';

package/src/tagging/persist_sender_tagging_index_ranges.ts

@@ -0,0 +1,57 @@
+import type { Logger } from '@aztec/foundation/log';
+import type { PrivateKernelTailCircuitPublicInputs } from '@aztec/stdlib/kernel';
+import type { TaggingIndexRange } from '@aztec/stdlib/logs';
+import type { TxHash } from '@aztec/stdlib/tx';
+
+import type { SenderTaggingStore } from '../storage/tagging_store/sender_tagging_store.js';
+import { reconcileTaggingIndexRangesAgainstSurvivingTags } from './reconcile_tagging_index_ranges.js';
+
+/**
+ * Persists the tagging index ranges that a tx used as a sender, after reconciling them against the kernel's surviving
+ * private logs.
+ *
+ * The tagging index cache reserves an index for every log emission attempted during private execution, but the kernel
+ * may then squash some of those logs (e.g. when a note is created and nullified within the same tx). This function
+ * shrinks the recorded ranges to match the actual on-chain footprint before writing them, so that what we persist is
+ * consistent with what the network will see.
+ *
+ * @remarks Storing the recorded ranges in the DB may not be seen as necessary because we sync from chain before sending
+ * new logs, but the sync can only see logs already included in blocks. If we sent another transaction before this one
+ * was included from the same PXE, and that transaction contained a log with a tag derived from the same secret, we
+ * would reuse the tag and the transactions would be linked. Persisting in the DB prevents that linkage.
+ *
+ * @param store - The sender tagging store.
+ * @param recordedRanges - The tagging index ranges as recorded during private execution (pre-squash).
+ * @param publicInputs - The final kernel public inputs, used to determine which private logs survived squashing.
+ * @param getTxHash - Lazy accessor for the tx hash. Called only when there is something to persist, since computing
+ * the tx hash is expensive.
+ * @param jobId - Job context for staged writes to the store. See `JobCoordinator` for more details.
+ * @param log - Logger.
+ */
+export async function persistSenderTaggingIndexRangesForTx(
+  store: SenderTaggingStore,
+  recordedRanges: TaggingIndexRange[],
+  publicInputs: PrivateKernelTailCircuitPublicInputs,
+  getTxHash: () => Promise<TxHash>,
+  jobId: string,
+  log: Logger,
+): Promise<void> {
+  if (recordedRanges.length === 0) {
+    log.debug(`No tagging index ranges used in the tx`);
+    return;
+  }
+
+  const survivingTags = new Set(
+    publicInputs.getNonEmptyPrivateLogs().map(privateLog => privateLog.fields[0].toString()),
+  );
+  const reconciledRanges = await reconcileTaggingIndexRangesAgainstSurvivingTags(recordedRanges, survivingTags);
+
+  if (reconciledRanges.length === 0) {
+    log.debug(`All tagging index ranges used in the tx were squashed by the kernel`, { recordedRanges });
+    return;
+  }
+
+  const txHash = await getTxHash();
+  await store.storePendingIndexes(reconciledRanges, txHash, jobId);
+  log.debug(`Stored used tagging index ranges as sender for the tx`, { recordedRanges, reconciledRanges });
+}