@aztec/stdlib 0.77.0-testnet-ignition.17

package/src/interfaces/server_circuit_prover.ts

@@ -0,0 +1,167 @@
+import type {
+  AVM_PROOF_LENGTH_IN_FIELDS,
+  NESTED_RECURSIVE_PROOF_LENGTH,
+  NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH,
+  RECURSIVE_PROOF_LENGTH,
+  TUBE_PROOF_LENGTH,
+} from '@aztec/constants';
+
+import type { AvmCircuitInputs } from '../avm/avm.js';
+import type { BaseParityInputs } from '../parity/base_parity_inputs.js';
+import type { ParityPublicInputs } from '../parity/parity_public_inputs.js';
+import type { RootParityInputs } from '../parity/root_parity_inputs.js';
+import type { BaseOrMergeRollupPublicInputs } from '../rollup/base_or_merge_rollup_public_inputs.js';
+import type { BlockMergeRollupInputs } from '../rollup/block_merge_rollup.js';
+import type { BlockRootOrBlockMergePublicInputs } from '../rollup/block_root_or_block_merge_public_inputs.js';
+import type { BlockRootRollupInputs, SingleTxBlockRootRollupInputs } from '../rollup/block_root_rollup.js';
+import type { EmptyBlockRootRollupInputs } from '../rollup/empty_block_root_rollup_inputs.js';
+import type { MergeRollupInputs } from '../rollup/merge_rollup.js';
+import type { PrivateBaseRollupInputs } from '../rollup/private_base_rollup_inputs.js';
+import type { PublicBaseRollupInputs } from '../rollup/public_base_rollup_inputs.js';
+import type { RootRollupInputs, RootRollupPublicInputs } from '../rollup/root_rollup.js';
+import type { TubeInputs } from '../rollup/tube_inputs.js';
+import type { Tx } from '../tx/tx.js';
+import type { ProofAndVerificationKey, PublicInputsAndRecursiveProof } from './proving-job.js';
+
+/**
+ * Generates proofs for parity and rollup circuits.
+ */
+export interface ServerCircuitProver {
+  /**
+   * Creates a proof for the given input.
+   * @param input - Input to the circuit.
+   */
+  getBaseParityProof(
+    inputs: BaseParityInputs,
+    signal?: AbortSignal,
+    epochNumber?: number,
+  ): Promise<PublicInputsAndRecursiveProof<ParityPublicInputs, typeof RECURSIVE_PROOF_LENGTH>>;
+
+  /**
+   * Creates a proof for the given input.
+   * @param input - Input to the circuit.
+   */
+  getRootParityProof(
+    inputs: RootParityInputs,
+    signal?: AbortSignal,
+    epochNumber?: number,
+  ): Promise<PublicInputsAndRecursiveProof<ParityPublicInputs, typeof NESTED_RECURSIVE_PROOF_LENGTH>>;
+
+  /**
+   * Creates a proof for the given input.
+   * @param input - Input to the circuit.
+   */
+  getPrivateBaseRollupProof(
+    baseRollupInput: PrivateBaseRollupInputs,
+    signal?: AbortSignal,
+    epochNumber?: number,
+  ): Promise<
+    PublicInputsAndRecursiveProof<BaseOrMergeRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
+  >;
+
+  getPublicBaseRollupProof(
+    inputs: PublicBaseRollupInputs,
+    signal?: AbortSignal,
+    epochNumber?: number,
+  ): Promise<
+    PublicInputsAndRecursiveProof<BaseOrMergeRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
+  >;
+
+  /**
+   * Get a recursively verified client IVC proof (making it a compatible honk proof for the rest of the rollup).
+   * @param input - Input to the circuit.
+   */
+  getTubeProof(
+    tubeInput: TubeInputs,
+    signal?: AbortSignal,
+    epochNumber?: number,
+  ): Promise<ProofAndVerificationKey<typeof TUBE_PROOF_LENGTH>>;
+
+  /**
+   * Creates a proof for the given input.
+   * @param input - Input to the circuit.
+   */
+  getMergeRollupProof(
+    input: MergeRollupInputs,
+    signal?: AbortSignal,
+    epochNumber?: number,
+  ): Promise<
+    PublicInputsAndRecursiveProof<BaseOrMergeRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
+  >;
+
+  /**
+   * Creates a proof for the given input.
+   * @param input - Input to the circuit.
+   */
+  getBlockRootRollupProof(
+    input: BlockRootRollupInputs,
+    signal?: AbortSignal,
+    epochNumber?: number,
+  ): Promise<
+    PublicInputsAndRecursiveProof<BlockRootOrBlockMergePublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
+  >;
+
+  getSingleTxBlockRootRollupProof(
+    input: SingleTxBlockRootRollupInputs,
+    signal?: AbortSignal,
+    epochNumber?: number,
+  ): Promise<
+    PublicInputsAndRecursiveProof<BlockRootOrBlockMergePublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
+  >;
+
+  /**
+   * Creates a proof for the given input.
+   * @param input - Input to the circuit.
+   */
+  getEmptyBlockRootRollupProof(
+    input: EmptyBlockRootRollupInputs,
+    signal?: AbortSignal,
+    epochNumber?: number,
+  ): Promise<
+    PublicInputsAndRecursiveProof<BlockRootOrBlockMergePublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
+  >;
+
+  /**
+   * Creates a proof for the given input.
+   * @param input - Input to the circuit.
+   */
+  getBlockMergeRollupProof(
+    input: BlockMergeRollupInputs,
+    signal?: AbortSignal,
+    epochNumber?: number,
+  ): Promise<
+    PublicInputsAndRecursiveProof<BlockRootOrBlockMergePublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
+  >;
+
+  /**
+   * Creates a proof for the given input.
+   * @param input - Input to the circuit.
+   */
+  getRootRollupProof(
+    input: RootRollupInputs,
+    signal?: AbortSignal,
+    epochNumber?: number,
+  ): Promise<PublicInputsAndRecursiveProof<RootRollupPublicInputs, typeof NESTED_RECURSIVE_PROOF_LENGTH>>;
+
+  /**
+   * Create a proof for the AVM circuit.
+   * @param inputs - Inputs to the AVM circuit.
+   */
+  getAvmProof(
+    inputs: AvmCircuitInputs,
+    signal?: AbortSignal,
+    epochNumber?: number,
+  ): Promise<ProofAndVerificationKey<typeof AVM_PROOF_LENGTH_IN_FIELDS>>;
+}
+
+/**
+ * A verifier used by nodes to check tx proofs are valid.
+ */
+export interface ClientProtocolCircuitVerifier {
+  /**
+   * Verifies the private protocol circuit's proof.
+   * @param tx - The tx to verify the proof of
+   * @returns True if the proof is valid, false otherwise
+   */
+  verifyProof(tx: Tx): Promise<boolean>;
+}

package/src/interfaces/service.ts

@@ -0,0 +1,25 @@
+import type { Logger } from '@aztec/foundation/log';
+import type { Maybe } from '@aztec/foundation/types';
+
+/** Represents a local service that can be started and stopped. */
+export interface Service {
+  /**
+   * Starts the service.
+   * @param waitUntilSynced - Whether to wait until the service is fully synched before returning.
+   */
+  start(waitUntilSynced?: boolean): Promise<void>;
+
+  /** Stops the service. */
+  stop(): Promise<void>;
+}
+
+/** Tries to call stop on a given object and awaits it. Logs any errors and does not rethrow. */
+export async function tryStop(service: Maybe<Service>, logger?: Logger): Promise<void> {
+  try {
+    return typeof service === 'object' && service && 'stop' in service && typeof service.stop === 'function'
+      ? await service.stop()
+      : Promise.resolve();
+  } catch (err) {
+    logger?.error(`Error stopping service ${(service as object).constructor?.name}: ${err}`);
+  }
+}

package/src/interfaces/world_state.ts

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+
+import type { MerkleTreeReadOperations, MerkleTreeWriteOperations } from './merkle_tree_operations.js';
+
+/**
+ * Defines the possible states of the world state synchronizer.
+ */
+export enum WorldStateRunningState {
+  IDLE,
+  SYNCHING,
+  RUNNING,
+  STOPPED,
+}
+
+export interface WorldStateSyncStatus {
+  latestBlockNumber: number;
+  latestBlockHash: string;
+  finalisedBlockNumber: number;
+  oldestHistoricBlockNumber: number;
+  treesAreSynched: boolean;
+}
+
+/**
+ * Defines the status of the world state synchronizer.
+ */
+export interface WorldStateSynchronizerStatus {
+  /**
+   * The current state of the world state synchronizer.
+   */
+  state: WorldStateRunningState;
+  /**
+   * The block numbers that the world state synchronizer is synced to.
+   */
+  syncSummary: WorldStateSyncStatus;
+}
+
+/** Provides writeable forks of the world state at a given block number. */
+export interface ForkMerkleTreeOperations {
+  /** Forks the world state at the given block number, defaulting to the latest one. */
+  fork(block?: number): Promise<MerkleTreeWriteOperations>;
+
+  /** Gets a handle that allows reading the state as it was at the given block number. */
+  getSnapshot(blockNumber: number): MerkleTreeReadOperations;
+}
+
+/** Defines the interface for a world state synchronizer. */
+export interface WorldStateSynchronizer extends ForkMerkleTreeOperations {
+  /**
+   * Starts the synchronizer.
+   * @returns A promise that resolves once the initial sync is completed.
+   */
+  start(): void;
+
+  /**
+   * Returns the current status of the synchronizer.
+   * @returns The current status of the synchronizer.
+   */
+  status(): Promise<WorldStateSynchronizerStatus>;
+
+  /**
+   * Stops the synchronizer.
+   */
+  stop(): Promise<void>;
+
+  /**
+   * Forces an immediate sync to an optionally provided minimum block number
+   * @param minBlockNumber - The minimum block number that we must sync to
+   * @returns A promise that resolves with the block number the world state was synced to
+   */
+  syncImmediate(minBlockNumber?: number): Promise<number>;
+
+  /**
+   * Returns an instance of MerkleTreeAdminOperations that will not include uncommitted data.
+   */
+  getCommitted(): MerkleTreeReadOperations;
+}
+
+export const WorldStateSyncStatusSchema = z.object({
+  finalisedBlockNumber: z.number(),
+  latestBlockNumber: z.number(),
+  latestBlockHash: z.string(),
+  oldestHistoricBlockNumber: z.number(),
+  treesAreSynched: z.boolean(),
+}) satisfies z.ZodType<WorldStateSyncStatus>;

package/src/kernel/combined_constant_data.ts

@@ -0,0 +1,128 @@
+import { Fr } from '@aztec/foundation/fields';
+import { type ZodFor, hexSchemaFor, schemas } from '@aztec/foundation/schemas';
+import { BufferReader, FieldReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import type { FieldsOf } from '@aztec/foundation/types';
+
+import { z } from 'zod';
+
+import { BlockHeader } from '../tx/block_header.js';
+import { GlobalVariables } from '../tx/global_variables.js';
+import type { TxConstantData } from '../tx/tx_constant_data.js';
+import { TxContext } from '../tx/tx_context.js';
+
+/**
+ * Data that is constant/not modified by neither of the kernels.
+ */
+export class CombinedConstantData {
+  constructor(
+    /** Header of a block whose state is used during execution (not the block the transaction is included in). */
+    public historicalHeader: BlockHeader,
+    /**
+     * Context of the transaction.
+     *
+     * Note: `chainId` and `version` in txContext are not redundant to the values in
+     * self.historical_header.global_variables because they can be different in case of a protocol upgrade. In such
+     * a situation we could be using header from a block before the upgrade took place but be using the updated
+     * protocol to execute and prove the transaction.
+     */
+    public txContext: TxContext,
+    /**
+     * Root of the vk tree for the protocol circuits.
+     */
+    public vkTreeRoot: Fr,
+    /**
+     * Root of the tree for the protocol contracts.
+     */
+    public protocolContractTreeRoot: Fr,
+    /** Present when output by a public kernel, empty otherwise. */
+    public globalVariables: GlobalVariables,
+  ) {}
+
+  static combine(TxConstantData: TxConstantData, globalVariables: GlobalVariables) {
+    return new CombinedConstantData(
+      TxConstantData.historicalHeader,
+      TxConstantData.txContext,
+      TxConstantData.vkTreeRoot,
+      TxConstantData.protocolContractTreeRoot,
+      globalVariables,
+    );
+  }
+
+  static get schema(): ZodFor<CombinedConstantData> {
+    return z
+      .object({
+        historicalHeader: BlockHeader.schema,
+        txContext: TxContext.schema,
+        vkTreeRoot: schemas.Fr,
+        protocolContractTreeRoot: schemas.Fr,
+        globalVariables: GlobalVariables.schema,
+      })
+      .transform(CombinedConstantData.from)
+      .or(hexSchemaFor(CombinedConstantData));
+  }
+
+  toBuffer() {
+    return serializeToBuffer(
+      this.historicalHeader,
+      this.txContext,
+      this.vkTreeRoot,
+      this.protocolContractTreeRoot,
+      this.globalVariables,
+    );
+  }
+
+  clone(): CombinedConstantData {
+    return CombinedConstantData.fromBuffer(this.toBuffer());
+  }
+
+  getSize() {
+    return (
+      this.historicalHeader.getSize() +
+      this.txContext.getSize() +
+      this.vkTreeRoot.size +
+      this.protocolContractTreeRoot.size +
+      this.globalVariables.getSize()
+    );
+  }
+
+  static from({
+    historicalHeader,
+    txContext,
+    vkTreeRoot,
+    protocolContractTreeRoot,
+    globalVariables,
+  }: FieldsOf<CombinedConstantData>): CombinedConstantData {
+    return new CombinedConstantData(historicalHeader, txContext, vkTreeRoot, protocolContractTreeRoot, globalVariables);
+  }
+
+  /**
+   * Deserializes from a buffer or reader, corresponding to a write in cpp.
+   * @param buffer - Buffer or buffer reader to read from.
+   * @returns A new instance of CombinedConstantData.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader): CombinedConstantData {
+    const reader = BufferReader.asReader(buffer);
+    return new CombinedConstantData(
+      reader.readObject(BlockHeader),
+      reader.readObject(TxContext),
+      Fr.fromBuffer(reader),
+      Fr.fromBuffer(reader),
+      reader.readObject(GlobalVariables),
+    );
+  }
+
+  static fromFields(fields: Fr[] | FieldReader): CombinedConstantData {
+    const reader = FieldReader.asReader(fields);
+    return new CombinedConstantData(
+      reader.readObject(BlockHeader),
+      reader.readObject(TxContext),
+      reader.readField(),
+      reader.readField(),
+      reader.readObject(GlobalVariables),
+    );
+  }
+
+  static empty() {
+    return new CombinedConstantData(BlockHeader.empty(), TxContext.empty(), Fr.ZERO, Fr.ZERO, GlobalVariables.empty());
+  }
+}

package/src/kernel/hints/build_note_hash_read_request_hints.ts

@@ -0,0 +1,125 @@
+import {
+  type MAX_NOTE_HASHES_PER_TX,
+  MAX_NOTE_HASH_READ_REQUESTS_PER_TX,
+  type NOTE_HASH_TREE_HEIGHT,
+} from '@aztec/constants';
+import type { Tuple } from '@aztec/foundation/serialize';
+import type { MembershipWitness } from '@aztec/foundation/trees';
+
+import type { ScopedNoteHash } from '../note_hash.js';
+import { countAccumulatedItems, getNonEmptyItems } from '../utils/order_and_comparison.js';
+import { NoteHashReadRequestHintsBuilder } from './note_hash_read_request_hints.js';
+import type { ScopedReadRequest } from './read_request.js';
+import { PendingReadHint, ReadRequestResetStates, ReadRequestState } from './read_request_hints.js';
+import { ScopedValueCache } from './scoped_value_cache.js';
+
+export function isValidNoteHashReadRequest(readRequest: ScopedReadRequest, noteHash: ScopedNoteHash) {
+  return (
+    noteHash.value.equals(readRequest.value) &&
+    noteHash.contractAddress.equals(readRequest.contractAddress) &&
+    readRequest.counter > noteHash.counter
+  );
+}
+
+export function getNoteHashReadRequestResetStates(
+  noteHashReadRequests: Tuple<ScopedReadRequest, typeof MAX_NOTE_HASH_READ_REQUESTS_PER_TX>,
+  noteHashes: Tuple<ScopedNoteHash, typeof MAX_NOTE_HASHES_PER_TX>,
+  futureNoteHashes: ScopedNoteHash[],
+): ReadRequestResetStates<typeof MAX_NOTE_HASH_READ_REQUESTS_PER_TX> {
+  const resetStates = ReadRequestResetStates.empty(MAX_NOTE_HASH_READ_REQUESTS_PER_TX);
+
+  const noteHashMap: Map<bigint, { noteHash: ScopedNoteHash; index: number }[]> = new Map();
+  getNonEmptyItems(noteHashes).forEach((noteHash, index) => {
+    const value = noteHash.value.toBigInt();
+    const arr = noteHashMap.get(value) ?? [];
+    arr.push({ noteHash, index });
+    noteHashMap.set(value, arr);
+  });
+
+  const futureNoteHashMap = new ScopedValueCache(futureNoteHashes);
+
+  const numReadRequests = countAccumulatedItems(noteHashReadRequests);
+  for (let i = 0; i < numReadRequests; ++i) {
+    const readRequest = noteHashReadRequests[i];
+
+    const pendingNoteHash = noteHashMap
+      .get(readRequest.value.toBigInt())
+      ?.find(n => isValidNoteHashReadRequest(readRequest, n.noteHash));
+
+    if (pendingNoteHash !== undefined) {
+      resetStates.states[i] = ReadRequestState.PENDING;
+      resetStates.pendingReadHints.push(new PendingReadHint(i, pendingNoteHash.index));
+    } else if (
+      !futureNoteHashMap
+        .get(readRequest)
+        .find(futureNoteHash => isValidNoteHashReadRequest(readRequest, futureNoteHash))
+    ) {
+      resetStates.states[i] = ReadRequestState.SETTLED;
+    }
+  }
+
+  return resetStates;
+}
+
+export async function buildNoteHashReadRequestHintsFromResetStates<PENDING extends number, SETTLED extends number>(
+  oracle: {
+    getNoteHashMembershipWitness(leafIndex: bigint): Promise<MembershipWitness<typeof NOTE_HASH_TREE_HEIGHT>>;
+  },
+  noteHashReadRequests: Tuple<ScopedReadRequest, typeof MAX_NOTE_HASH_READ_REQUESTS_PER_TX>,
+  noteHashes: Tuple<ScopedNoteHash, typeof MAX_NOTE_HASHES_PER_TX>,
+  resetStates: ReadRequestResetStates<typeof MAX_NOTE_HASH_READ_REQUESTS_PER_TX>,
+  noteHashLeafIndexMap: Map<bigint, bigint>,
+  maxPending: PENDING = MAX_NOTE_HASH_READ_REQUESTS_PER_TX as PENDING,
+  maxSettled: SETTLED = MAX_NOTE_HASH_READ_REQUESTS_PER_TX as SETTLED,
+) {
+  const builder = new NoteHashReadRequestHintsBuilder(maxPending, maxSettled);
+
+  resetStates.pendingReadHints.forEach(hint => {
+    builder.addPendingReadRequest(hint.readRequestIndex, hint.pendingValueIndex);
+  });
+
+  for (let i = 0; i < resetStates.states.length; i++) {
+    if (resetStates.states[i] === ReadRequestState.SETTLED) {
+      const readRequest = noteHashReadRequests[i];
+      const leafIndex = noteHashLeafIndexMap.get(readRequest.value.toBigInt());
+      if (leafIndex === undefined) {
+        throw new Error('Read request is reading an unknown note hash.');
+      }
+      const membershipWitness = await oracle.getNoteHashMembershipWitness(leafIndex);
+      builder.addSettledReadRequest(i, membershipWitness, readRequest.value);
+    }
+  }
+
+  const noteHashMap: Map<bigint, { noteHash: ScopedNoteHash; index: number }[]> = new Map();
+  getNonEmptyItems(noteHashes).forEach((noteHash, index) => {
+    const value = noteHash.value.toBigInt();
+    const arr = noteHashMap.get(value) ?? [];
+    arr.push({ noteHash, index });
+    noteHashMap.set(value, arr);
+  });
+
+  return builder.toHints();
+}
+
+export async function buildNoteHashReadRequestHints<PENDING extends number, SETTLED extends number>(
+  oracle: {
+    getNoteHashMembershipWitness(leafIndex: bigint): Promise<MembershipWitness<typeof NOTE_HASH_TREE_HEIGHT>>;
+  },
+  noteHashReadRequests: Tuple<ScopedReadRequest, typeof MAX_NOTE_HASH_READ_REQUESTS_PER_TX>,
+  noteHashes: Tuple<ScopedNoteHash, typeof MAX_NOTE_HASHES_PER_TX>,
+  noteHashLeafIndexMap: Map<bigint, bigint>,
+  futureNoteHashes: ScopedNoteHash[],
+  maxPending: PENDING = MAX_NOTE_HASH_READ_REQUESTS_PER_TX as PENDING,
+  maxSettled: SETTLED = MAX_NOTE_HASH_READ_REQUESTS_PER_TX as SETTLED,
+) {
+  const resetStates = getNoteHashReadRequestResetStates(noteHashReadRequests, noteHashes, futureNoteHashes);
+  return await buildNoteHashReadRequestHintsFromResetStates(
+    oracle,
+    noteHashReadRequests,
+    noteHashes,
+    resetStates,
+    noteHashLeafIndexMap,
+    maxPending,
+    maxSettled,
+  );
+}

package/src/kernel/hints/build_nullifier_read_request_hints.ts

@@ -0,0 +1,153 @@
+import {
+  type MAX_NULLIFIERS_PER_TX,
+  MAX_NULLIFIER_READ_REQUESTS_PER_TX,
+  type NULLIFIER_TREE_HEIGHT,
+} from '@aztec/constants';
+import { padArrayEnd } from '@aztec/foundation/collection';
+import type { Fr } from '@aztec/foundation/fields';
+import type { Tuple } from '@aztec/foundation/serialize';
+import { type IndexedTreeLeafPreimage, MembershipWitness } from '@aztec/foundation/trees';
+
+import { AztecAddress } from '../../aztec-address/index.js';
+import { siloNullifier } from '../../hash/hash.js';
+import { Nullifier, type ScopedNullifier } from '../nullifier.js';
+import { countAccumulatedItems, getNonEmptyItems } from '../utils/order_and_comparison.js';
+import { NullifierReadRequestHintsBuilder } from './nullifier_read_request_hints.js';
+import { ReadRequest, ScopedReadRequest } from './read_request.js';
+import { PendingReadHint, ReadRequestResetStates, ReadRequestState } from './read_request_hints.js';
+import { ScopedValueCache } from './scoped_value_cache.js';
+
+export function isValidNullifierReadRequest(readRequest: ScopedReadRequest, nullifier: ScopedNullifier) {
+  return (
+    readRequest.value.equals(nullifier.value) &&
+    nullifier.contractAddress.equals(readRequest.contractAddress) &&
+    readRequest.counter > nullifier.counter
+  );
+}
+
+interface NullifierMembershipWitnessWithPreimage {
+  membershipWitness: MembershipWitness<typeof NULLIFIER_TREE_HEIGHT>;
+  leafPreimage: IndexedTreeLeafPreimage;
+}
+
+export function getNullifierReadRequestResetStates(
+  nullifierReadRequests: Tuple<ScopedReadRequest, typeof MAX_NULLIFIER_READ_REQUESTS_PER_TX>,
+  nullifiers: Tuple<ScopedNullifier, typeof MAX_NULLIFIERS_PER_TX>,
+  futureNullifiers: ScopedNullifier[],
+): ReadRequestResetStates<typeof MAX_NULLIFIER_READ_REQUESTS_PER_TX> {
+  const resetStates = ReadRequestResetStates.empty(MAX_NULLIFIER_READ_REQUESTS_PER_TX);
+
+  const nullifierMap: Map<bigint, { nullifier: ScopedNullifier; index: number }[]> = new Map();
+  getNonEmptyItems(nullifiers).forEach((nullifier, index) => {
+    const value = nullifier.value.toBigInt();
+    const arr = nullifierMap.get(value) ?? [];
+    arr.push({ nullifier, index });
+    nullifierMap.set(value, arr);
+  });
+
+  const futureNullifiersMap = new ScopedValueCache(futureNullifiers);
+
+  const numReadRequests = countAccumulatedItems(nullifierReadRequests);
+
+  for (let i = 0; i < numReadRequests; ++i) {
+    const readRequest = nullifierReadRequests[i];
+    const pendingNullifier = nullifierMap
+      .get(readRequest.value.toBigInt())
+      ?.find(({ nullifier }) => isValidNullifierReadRequest(readRequest, nullifier));
+
+    if (pendingNullifier !== undefined) {
+      resetStates.states[i] = ReadRequestState.PENDING;
+      resetStates.pendingReadHints.push(new PendingReadHint(i, pendingNullifier.index));
+    } else if (
+      !futureNullifiersMap
+        .get(readRequest)
+        .some(futureNullifier => isValidNullifierReadRequest(readRequest, futureNullifier))
+    ) {
+      resetStates.states[i] = ReadRequestState.SETTLED;
+    }
+  }
+
+  return resetStates;
+}
+
+export async function buildNullifierReadRequestHintsFromResetStates<PENDING extends number, SETTLED extends number>(
+  oracle: {
+    getNullifierMembershipWitness(nullifier: Fr): Promise<NullifierMembershipWitnessWithPreimage>;
+  },
+  nullifierReadRequests: Tuple<ScopedReadRequest, typeof MAX_NULLIFIER_READ_REQUESTS_PER_TX>,
+  resetStates: ReadRequestResetStates<typeof MAX_NULLIFIER_READ_REQUESTS_PER_TX>,
+  maxPending: PENDING = MAX_NULLIFIER_READ_REQUESTS_PER_TX as PENDING,
+  maxSettled: SETTLED = MAX_NULLIFIER_READ_REQUESTS_PER_TX as SETTLED,
+  siloed = false,
+) {
+  const builder = new NullifierReadRequestHintsBuilder(maxPending, maxSettled);
+
+  resetStates.pendingReadHints.forEach(hint => {
+    builder.addPendingReadRequest(hint.readRequestIndex, hint.pendingValueIndex);
+  });
+
+  for (let i = 0; i < resetStates.states.length; i++) {
+    if (resetStates.states[i] === ReadRequestState.SETTLED) {
+      const readRequest = nullifierReadRequests[i];
+      const siloedValue = siloed
+        ? readRequest.value
+        : await siloNullifier(readRequest.contractAddress, readRequest.value);
+      const membershipWitnessWithPreimage = await oracle.getNullifierMembershipWitness(siloedValue);
+      builder.addSettledReadRequest(
+        i,
+        membershipWitnessWithPreimage.membershipWitness,
+        membershipWitnessWithPreimage.leafPreimage,
+      );
+    }
+  }
+
+  return builder.toHints();
+}
+
+export async function buildNullifierReadRequestHints<PENDING extends number, SETTLED extends number>(
+  oracle: {
+    getNullifierMembershipWitness(nullifier: Fr): Promise<NullifierMembershipWitnessWithPreimage>;
+  },
+  nullifierReadRequests: Tuple<ScopedReadRequest, typeof MAX_NULLIFIER_READ_REQUESTS_PER_TX>,
+  nullifiers: Tuple<ScopedNullifier, typeof MAX_NULLIFIERS_PER_TX>,
+  futureNullifiers: ScopedNullifier[],
+  maxPending: PENDING = MAX_NULLIFIER_READ_REQUESTS_PER_TX as PENDING,
+  maxSettled: SETTLED = MAX_NULLIFIER_READ_REQUESTS_PER_TX as SETTLED,
+  siloed = false,
+) {
+  const resetStates = getNullifierReadRequestResetStates(nullifierReadRequests, nullifiers, futureNullifiers);
+  return await buildNullifierReadRequestHintsFromResetStates(
+    oracle,
+    nullifierReadRequests,
+    resetStates,
+    maxPending,
+    maxSettled,
+    siloed,
+  );
+}
+
+export async function buildSiloedNullifierReadRequestHints<PENDING extends number, SETTLED extends number>(
+  oracle: {
+    getNullifierMembershipWitness(nullifier: Fr): Promise<NullifierMembershipWitnessWithPreimage>;
+  },
+  nullifierReadRequests: Tuple<ScopedReadRequest, typeof MAX_NULLIFIER_READ_REQUESTS_PER_TX>,
+  nullifiers: Tuple<Nullifier, typeof MAX_NULLIFIERS_PER_TX>,
+  maxPending: PENDING = MAX_NULLIFIER_READ_REQUESTS_PER_TX as PENDING,
+  maxSettled: SETTLED = MAX_NULLIFIER_READ_REQUESTS_PER_TX as SETTLED,
+) {
+  // Nullifiers outputted from public kernels are already siloed while read requests are not.
+  // Siloing the read request values and set the contract addresses to zero to find the matching nullifier contexts.
+  const nonEmptyNullifierReadRequests = getNonEmptyItems(nullifierReadRequests);
+  const readRequests = await Promise.all(
+    nonEmptyNullifierReadRequests.map(async r =>
+      new ReadRequest(await siloNullifier(r.contractAddress, r.value), r.counter).scope(AztecAddress.ZERO),
+    ),
+  );
+  const siloedReadRequests = padArrayEnd(readRequests, ScopedReadRequest.empty(), MAX_NULLIFIER_READ_REQUESTS_PER_TX);
+
+  const scopedNullifiers = nullifiers.map(n =>
+    new Nullifier(n.value, n.counter, n.noteHash).scope(AztecAddress.ZERO),
+  ) as Tuple<ScopedNullifier, typeof MAX_NULLIFIERS_PER_TX>;
+
+  return buildNullifierReadRequestHints(oracle, siloedReadRequests, scopedNullifiers, [], maxPending, maxSettled, true);
+}