@aztec/pxe 0.0.1-commit.d431d1c → 0.0.1-commit.d58ff9d0

package/src/entrypoints/server/store.ts

@@ -0,0 +1,47 @@
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import { type LoggerBindings, createLogger } from '@aztec/foundation/log';
+import { type AztecLMDBStoreV2, openStoreAt } from '@aztec/kv-store/lmdb-v2';
+
+import { mkdir } from 'fs/promises';
+import { join } from 'path';
+
+import { storeIdentitySlug } from '../../storage/store_identity.js';
+
+/** Location and identity inputs for opening an identity-partitioned PXE-side store. */
+export type IdentityStoreConfig = {
+  dataDirectory: string;
+  /** Maximum LMDB map size in KB. When omitted, the kv-store default map size applies. */
+  dataStoreMapSizeKb?: number;
+  l1ChainId: number;
+  rollupAddress: EthAddress;
+};
+
+/**
+ * Opens the persistent LMDB store selected by `name` and identity triple `(l1ChainId, rollupAddress, schemaVersion)`.
+ * A store exists per identity: reopening with the same identity returns the same data, a different identity selects
+ * a different (possibly fresh) store. Callers wanting an ephemeral store use `openTmpStore` explicitly instead.
+ */
+export async function openStore(
+  name: string,
+  schemaVersion: number,
+  config: IdentityStoreConfig,
+  bindings?: LoggerBindings,
+): Promise<AztecLMDBStoreV2> {
+  // Stores live under `<dataDirectory>/<name>-stores/<l1ChainId>-<rollupAddress>-v<schemaVersion>`, a sibling of the
+  // legacy `<dataDirectory>/<name>` directory: older binaries reset the legacy directory on a rollup mismatch, so
+  // per-identity stores must not nest inside it.
+  const subDir = join(
+    config.dataDirectory,
+    `${name}-stores`,
+    storeIdentitySlug({ l1ChainId: config.l1ChainId, rollupAddress: config.rollupAddress, schemaVersion }),
+  );
+  await mkdir(subDir, { recursive: true });
+
+  createLogger(`pxe:data:${name}`, bindings).info(`Opening ${name} data store (LMDB v2)`, {
+    storeName: name,
+    subDir,
+    dataStoreMapSizeKb: config.dataStoreMapSizeKb,
+  });
+
+  return openStoreAt(subDir, config.dataStoreMapSizeKb, undefined, bindings);
+}

package/src/entrypoints/server/utils.ts

@@ -1,75 +1,102 @@
-import { BBPrivateKernelProver } from '@aztec/bb-prover/client';
 import { BBBundlePrivateKernelProver } from '@aztec/bb-prover/client/bundle';
-import { randomBytes } from '@aztec/foundation/crypto/random';
+import type { L1ContractAddresses } from '@aztec/ethereum/l1-contract-addresses';
 import { createLogger } from '@aztec/foundation/log';
-import { createStore } from '@aztec/kv-store/lmdb-v2';
+import { openTmpStore } from '@aztec/kv-store/lmdb-v2';
 import { BundledProtocolContractsProvider } from '@aztec/protocol-contracts/providers/bundle';
-import { MemoryCircuitRecorder, SimulatorRecorderWrapper, WASMSimulator } from '@aztec/simulator/client';
+import { WASMSimulator } from '@aztec/simulator/client';
+import { MemoryCircuitRecorder, SimulatorRecorderWrapper } from '@aztec/simulator/server';
 import { FileCircuitRecorder } from '@aztec/simulator/testing';
+import { getStandardAuthRegistry } from '@aztec/standard-contracts/auth-registry';
+import { getStandardHandshakeRegistry } from '@aztec/standard-contracts/handshake-registry';
+import { getStandardMultiCallEntrypoint } from '@aztec/standard-contracts/multi-call-entrypoint';
 import type { AztecNode } from '@aztec/stdlib/interfaces/client';
 
 import type { PXEConfig } from '../../config/index.js';
 import { PXE } from '../../pxe.js';
 import { PXE_DATA_SCHEMA_VERSION } from '../../storage/index.js';
-import type { PXECreationOptions } from '../pxe_creation_options.js';
+import { type PXECreationOptions, isPrivateKernelProver } from '../pxe_creation_options.js';
+import { openStore } from './store.js';
 
-type PXEConfigWithoutDefaults = Omit<PXEConfig, 'l1Contracts' | 'l1ChainId' | 'l2BlockBatchSize' | 'rollupVersion'>;
+type PXEConfigWithoutDefaults = Omit<
+  PXEConfig,
+  'l1ChainId' | 'l2BlockBatchSize' | 'rollupVersion' | keyof L1ContractAddresses
+>;
 
 export async function createPXE(
   aztecNode: AztecNode,
   config: PXEConfigWithoutDefaults,
   options: PXECreationOptions = { loggers: {} },
 ) {
+  const actor = options.loggerActorLabel;
+  const recorderLogger = createLogger('simulator:acvm:recording', { actor });
   const recorder = process.env.CIRCUIT_RECORD_DIR
-    ? new FileCircuitRecorder(process.env.CIRCUIT_RECORD_DIR)
-    : new MemoryCircuitRecorder();
-  const simulator = new SimulatorRecorderWrapper(new WASMSimulator(), recorder);
-
-  const logSuffix =
-    typeof options.useLogSuffix === 'boolean'
-      ? options.useLogSuffix
-        ? randomBytes(3).toString('hex')
-        : undefined
-      : options.useLogSuffix;
+    ? new FileCircuitRecorder(process.env.CIRCUIT_RECORD_DIR, recorderLogger)
+    : new MemoryCircuitRecorder(recorderLogger);
+  const simulatorLogger = createLogger('wasm-simulator', { actor });
+  const simulator = new SimulatorRecorderWrapper(new WASMSimulator(simulatorLogger), recorder);
   const loggers = options.loggers ?? {};
 
-  const { l1ChainId, l1ContractAddresses: l1Contracts, rollupVersion } = await aztecNode.getNodeInfo();
+  const { l1ChainId, l1ContractAddresses, rollupVersion } = await aztecNode.getNodeInfo();
   const configWithContracts: PXEConfig = {
     ...config,
-    l1Contracts,
+    ...l1ContractAddresses,
     l1ChainId,
     rollupVersion,
     l2BlockBatchSize: 50,
   };
 
   if (!options.store) {
-    const storeLogger = loggers.store
-      ? loggers.store
-      : createLogger('pxe:data:lmdb' + (logSuffix ? `:${logSuffix}` : ''));
-    options.store = await createStore('pxe_data', PXE_DATA_SCHEMA_VERSION, configWithContracts, storeLogger);
+    const storeLogger = loggers.store ?? createLogger('pxe:data:lmdb', { actor });
+    options.store = configWithContracts.dataDirectory
+      ? await openStore(
+          'pxe_data',
+          PXE_DATA_SCHEMA_VERSION,
+          {
+            dataDirectory: configWithContracts.dataDirectory,
+            dataStoreMapSizeKb: configWithContracts.dataStoreMapSizeKb,
+            l1ChainId,
+            rollupAddress: l1ContractAddresses.rollupAddress,
+          },
+          storeLogger.getBindings(),
+        )
+      : await openTmpStore(
+          'pxe_data',
+          true,
+          configWithContracts.dataStoreMapSizeKb,
+          undefined,
+          storeLogger.getBindings(),
+        );
   }
-  const proverLogger = loggers.prover
-    ? loggers.prover
-    : createLogger('pxe:bb:native' + (logSuffix ? `:${logSuffix}` : ''));
+  const proverLogger = loggers.prover ?? createLogger('pxe:bb:native', { actor });
 
   let prover;
-  if (options.proverOrOptions instanceof BBPrivateKernelProver) {
+  if (isPrivateKernelProver(options.proverOrOptions)) {
     prover = options.proverOrOptions;
   } else {
     prover = new BBBundlePrivateKernelProver(simulator, { ...options.proverOrOptions, logger: proverLogger });
   }
 
   const protocolContractsProvider = new BundledProtocolContractsProvider();
+  const preloadedContractsProvider = options.preloadedContractsProvider ?? {
+    getPreloadedContracts: async () => [
+      await getStandardMultiCallEntrypoint(),
+      await getStandardAuthRegistry(),
+      await getStandardHandshakeRegistry(),
+    ],
+  };
 
-  const pxeLogger = loggers.pxe ? loggers.pxe : createLogger('pxe:service' + (logSuffix ? `:${logSuffix}` : ''));
-  const pxe = await PXE.create(
-    aztecNode,
-    options.store,
-    prover,
+  const pxeLogger = loggers.pxe ?? createLogger('pxe:service', { actor });
+  const pxe = await PXE.create({
+    node: aztecNode,
+    nodeDebug: options.nodeDebug,
+    store: options.store,
+    proofCreator: prover,
     simulator,
     protocolContractsProvider,
-    configWithContracts,
-    pxeLogger,
-  );
+    preloadedContractsProvider,
+    config: configWithContracts,
+    loggerOrSuffix: pxeLogger,
+    hooks: options.hooks,
+  });
   return pxe;
 }

package/src/error_enriching.ts

@@ -3,7 +3,9 @@ import { resolveAssertionMessageFromRevertData, resolveOpcodeLocations } from '@
 import { FunctionSelector } from '@aztec/stdlib/abi';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import { type SimulationError, isNoirCallStackUnresolved } from '@aztec/stdlib/errors';
+import type { BlockHeader } from '@aztec/stdlib/tx';
 
+import type { ContractClassService } from './contract/contract_class_service.js';
 import type { ContractStore } from './storage/contract_store/contract_store.js';
 
 /**
@@ -11,7 +13,13 @@ import type { ContractStore } from './storage/contract_store/contract_store.js';
  * can be found in the PXE database
  * @param err - The error to enrich.
  */
-export async function enrichSimulationError(err: SimulationError, contractStore: ContractStore, logger: Logger) {
+export async function enrichSimulationError(
+  err: SimulationError,
+  contractStore: ContractStore,
+  contractClassService: ContractClassService,
+  anchorHeader: BlockHeader,
+  logger: Logger,
+) {
   // Maps contract addresses to the set of function selectors that were in error.
   // Map and Set do reference equality for their keys instead of value equality, so we store the string
   // representation to get e.g. different contract address objects with the same address value to match.
@@ -29,14 +37,15 @@ export async function enrichSimulationError(err: SimulationError, contractStore:
 
   await Promise.all(
     [...mentionedFunctions.entries()].map(async ([contractAddress, fnSelectors]) => {
-      const parsedContractAddress = AztecAddress.fromString(contractAddress);
-      const contract = await contractStore.getContract(parsedContractAddress);
-      if (contract) {
-        err.enrichWithContractName(parsedContractAddress, contract.name);
+      const parsedContractAddress = AztecAddress.fromStringUnsafe(contractAddress);
+      const classId = await contractClassService.getCurrentClassId(parsedContractAddress, anchorHeader);
+      const artifact = classId && (await contractStore.getContractArtifact(classId));
+      if (artifact) {
+        err.enrichWithContractName(parsedContractAddress, artifact.name);
         // Map from function selector to function name. It uses a stringified key for the same reason as mentionedFunctions.
         const selectorToNameMap: Map<string, string> = new Map();
         await Promise.all(
-          contract.functions.map(async fn => {
+          artifact.functions.map(async fn => {
             const selector = await FunctionSelector.fromNameAndParameters(fn);
             selectorToNameMap.set(selector.toString(), fn.name);
           }),
@@ -51,7 +60,7 @@ export async function enrichSimulationError(err: SimulationError, contractStore:
             );
           } else {
             logger.warn(
-              `Could not find function artifact in contract ${contract.name} for function '${fnSelector}' when enriching error callstack`,
+              `Could not find function artifact in contract ${artifact.name} for function '${fnSelector}' when enriching error callstack`,
             );
           }
         }
@@ -64,7 +73,13 @@ export async function enrichSimulationError(err: SimulationError, contractStore:
   );
 }
 
-export async function enrichPublicSimulationError(err: SimulationError, contractStore: ContractStore, logger: Logger) {
+export async function enrichPublicSimulationError(
+  err: SimulationError,
+  contractStore: ContractStore,
+  contractClassService: ContractClassService,
+  anchorHeader: BlockHeader,
+  logger: Logger,
+) {
   const callStack = err.getCallStack();
   const originalFailingFunction = callStack[callStack.length - 1];
 
@@ -72,7 +87,8 @@ export async function enrichPublicSimulationError(err: SimulationError, contract
     throw new Error(`Original failing function not found when enriching public simulation, missing callstack`);
   }
 
-  const artifact = await contractStore.getPublicFunctionArtifact(originalFailingFunction.contractAddress);
+  const classId = await contractClassService.getCurrentClassId(originalFailingFunction.contractAddress, anchorHeader);
+  const artifact = classId && (await contractStore.getPublicFunctionArtifact(classId));
   if (!artifact) {
     throw new Error(
       `Artifact not found when enriching public simulation error. Contract address: ${originalFailingFunction.contractAddress}.`,
@@ -84,7 +100,7 @@ export async function enrichPublicSimulationError(err: SimulationError, contract
     err.setOriginalMessage(err.getOriginalMessage() + `${assertionMessage}`);
   }
 
-  const debugInfo = await contractStore.getPublicFunctionDebugMetadata(originalFailingFunction.contractAddress);
+  const debugInfo = await contractStore.getPublicFunctionDebugMetadata(classId);
 
   const noirCallStack = err.getNoirCallStack();
   if (debugInfo) {
@@ -102,6 +118,6 @@ export async function enrichPublicSimulationError(err: SimulationError, contract
         );
       }
     }
-    await enrichSimulationError(err, contractStore, logger);
+    await enrichSimulationError(err, contractStore, contractClassService, anchorHeader, logger);
   }
 }

package/src/events/event_service.ts

@@ -1,56 +1,102 @@
-import type { Fr } from '@aztec/foundation/curves/bn254';
-import type { EventSelector } from '@aztec/stdlib/abi';
+import { createLogger } from '@aztec/foundation/log';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
-import { siloNullifier } from '@aztec/stdlib/hash';
+import { computePrivateEventCommitment, siloNullifier } from '@aztec/stdlib/hash';
 import type { AztecNode } from '@aztec/stdlib/interfaces/server';
-import type { TxHash } from '@aztec/stdlib/tx';
+import type { BlockHeader, IndexedTxEffect } from '@aztec/stdlib/tx';
 
-import { AnchorBlockStore } from '../storage/anchor_block_store/anchor_block_store.js';
+import type { EventValidationRequest } from '../contract_function_simulator/noir-structs/event_validation_request.js';
 import { PrivateEventStore } from '../storage/private_event_store/private_event_store.js';
 
 export class EventService {
   constructor(
-    private readonly anchorBlockStore: AnchorBlockStore,
+    private readonly anchorBlockHeader: BlockHeader,
     private readonly aztecNode: AztecNode,
     private readonly privateEventStore: PrivateEventStore,
     private readonly jobId: string,
+    private readonly log = createLogger('pxe:event_service'),
   ) {}
 
-  public async storeEvent(
-    contractAddress: AztecAddress,
-    selector: EventSelector,
-    randomness: Fr,
-    content: Fr[],
-    eventCommitment: Fr,
-    txHash: TxHash,
+  /**
+   * Validates and stores a batch of private events against pre-fetched tx effects.
+   *
+   * @param requests - The events to validate and store.
+   * @param scope - The scope under which the events are being stored.
+   * @param txEffects - Pre-fetched tx effects keyed by `TxHash.toString()`. Must contain entries for every request's
+   *                   txHash; missing entries are treated as a node bug and cause an error.
+   */
+  public async validateAndStoreEvents(
+    requests: EventValidationRequest[],
     scope: AztecAddress,
+    txEffects: Map<string, IndexedTxEffect>,
   ): Promise<void> {
+    if (requests.length === 0) {
+      return;
+    }
+
+    const anchorBlockNumber = this.anchorBlockHeader.getBlockNumber();
+
+    await Promise.all(requests.map(req => this.#validateAndStoreEvent(req, scope, txEffects, anchorBlockNumber)));
+  }
+
+  async #validateAndStoreEvent(
+    request: EventValidationRequest,
+    scope: AztecAddress,
+    txEffects: Map<string, IndexedTxEffect>,
+    anchorBlockNumber: number,
+  ): Promise<void> {
+    const {
+      contractAddress,
+      eventTypeId: selector,
+      randomness,
+      serializedEvent: content,
+      eventCommitment,
+      txHash,
+    } = request;
+
+    // Defense-in-depth: the built-in private-event path derives this commitment from content before enqueueing, but
+    // unconstrained PXE-side code (e.g. a custom message handler) can reach this oracle with arbitrary
+    // (content, commitment) pairs. Without this check it could bind arbitrary content to a legitimate tx nullifier,
+    // causing PXE to surface fabricated event data.
+    const recomputedCommitment = await computePrivateEventCommitment(randomness, selector.toField(), content);
+    if (!recomputedCommitment.equals(eventCommitment)) {
+      this.log.warn(
+        `Skipping event whose content does not hash to the provided commitment. contract=${contractAddress}, selector=${selector}, eventCommitment=${eventCommitment}, txHash=${txHash}, recomputedCommitment=${recomputedCommitment}`,
+      );
+      return;
+    }
+
     // While using 'latest' block number would be fine for private events since they cannot be accessed from Aztec.nr
     // (and thus we're less concerned about being ahead of the synced block), we use the synced block number to
     // maintain consistent behavior in the PXE. Additionally, events should never be ahead of the synced block here
     // since `fetchTaggedLogs` only processes logs up to the synced block.
-    const [anchorBlockHeader, siloedEventCommitment, txEffect] = await Promise.all([
-      this.anchorBlockStore.getBlockHeader(),
-      siloNullifier(contractAddress, eventCommitment),
-      this.aztecNode.getTxEffect(txHash),
-    ]);
-
-    const anchorBlockNumber = anchorBlockHeader.getBlockNumber();
+    const siloedEventCommitment = await siloNullifier(contractAddress, eventCommitment);
 
+    const txEffect = txEffects.get(txHash.toString());
     if (!txEffect) {
-      throw new Error(`Could not find tx effect for tx hash ${txHash}`);
+      // We error out instead of just logging a warning and skipping the event because this would indicate a bug. This
+      // is because the node has already served info about this tx either when obtaining the log (LogResult carries
+      // the tx info) or when getting metadata for the offchain message (before the message got passed to `process_log`).
+      throw new Error(`Could not find tx effect for tx hash ${txHash} when processing an event.`);
     }
 
     if (txEffect.l2BlockNumber > anchorBlockNumber) {
-      throw new Error(`Could not find tx effect for tx hash ${txHash} as of block number ${anchorBlockNumber}`);
+      // We should never process a message from a tx past the anchor block. If we got here, a preprocessing step made
+      // a mistake.
+      throw new Error(
+        `Obtained a newer tx effect for ${txHash} for an event validation request than the anchor block ${anchorBlockNumber}. This is a bug as smart contracts should not issue event validation requests for events from blocks newer than the anchor block.`,
+      );
     }
 
     // Find the index of the event commitment in the nullifiers array to determine event ordering within the tx
     const eventIndexInTx = txEffect.data.nullifiers.findIndex(n => n.equals(siloedEventCommitment));
     if (eventIndexInTx === -1) {
-      throw new Error(
-        `Event commitment ${eventCommitment} (siloed as ${siloedEventCommitment}) is not present in tx ${txHash}`,
+      // Unlike in NoteService, this might not be a bug since the commitment hasn't been verified yet in the message
+      // processing pipeline. A malformed or malicious message could trigger this condition. Because of this we don't
+      // error out and we just show a warning.
+      this.log.warn(
+        `Skipping event whose commitment is not present in its tx. siloedEventCommitment=${siloedEventCommitment}, contract=${contractAddress}, selector=${selector}, eventCommitment=${eventCommitment}, txHash=${txHash}`,
       );
+      return;
     }
 
     return this.privateEventStore.storePrivateEventLog(

package/src/events/private_event_filter_validator.ts

@@ -1,11 +1,14 @@
 import type { PrivateEventFilter } from '@aztec/aztec.js/wallet';
 import { INITIAL_L2_BLOCK_NUM } from '@aztec/constants';
 import { BlockNumber } from '@aztec/foundation/branded-types';
+import { createLogger } from '@aztec/foundation/log';
 
 import type { PrivateEventStoreFilter } from '../storage/private_event_store/private_event_store.js';
 
 export class PrivateEventFilterValidator {
-  constructor(private lastBlock: BlockNumber) {}
+  private readonly log = createLogger('pxe:private_event_filter_validator');
+
+  constructor(private readonly lastBlock: BlockNumber) {}
 
   validate(filter: PrivateEventFilter): PrivateEventStoreFilter {
     let { fromBlock, toBlock } = filter;
@@ -35,6 +38,23 @@ export class PrivateEventFilterValidator {
       throw new Error('toBlock must be strictly greater than fromBlock');
     }
 
+    // Cap the requested range to the synced block range. Without this, callers that pass a large
+    // toBlock (e.g. Number.MAX_SAFE_INTEGER as a "give me everything" idiom) would silently receive
+    // only the events that happen to be synced and believe they have complete coverage.
+    // We warn + cap rather than throw so callers don't need to query the last synced block before
+    // every request (which would also be unreliable, as the block can advance between the two calls).
+    const syncedUpperBound = BlockNumber(this.lastBlock + 1);
+    if (fromBlock >= syncedUpperBound) {
+      this.log.warn(
+        `Requested fromBlock ${fromBlock} is past last synced block ${this.lastBlock}; no events will be returned until PXE syncs further.`,
+      );
+    } else if (toBlock > syncedUpperBound) {
+      this.log.warn(
+        `Requested toBlock ${toBlock} exceeds last synced block ${this.lastBlock}; capping to ${syncedUpperBound}. Retry once PXE is further synced for complete coverage.`,
+      );
+      toBlock = syncedUpperBound;
+    }
+
     return {
       contractAddress: filter.contractAddress,
       scopes: filter.scopes,

package/src/hooks/authorize_utility_call.ts

@@ -0,0 +1,44 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { FunctionSelector } from '@aztec/stdlib/abi';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+
+/** Information about a cross-contract utility call that requires authorization. */
+export type UtilityCallAuthorizationRequest = {
+  /** The contract requesting the cross-contract call. */
+  caller: AztecAddress;
+  /** The contract class ID of the calling contract. */
+  callerClassId: Fr;
+  /** The target contract being called. */
+  target: AztecAddress;
+  /** The contract class ID of the target contract. */
+  targetClassId: Fr;
+  /** The function selector being invoked on the target. */
+  functionSelector: FunctionSelector;
+  /** The name of the function being called, from the contract artifact. */
+  functionName: string;
+  /** The serialized arguments passed to the function. */
+  args: Fr[];
+  /** The execution context from which the call originates. */
+  callerContext: 'private' | 'private view' | 'utility';
+};
+
+/** Authorization was granted. */
+type Authorized = { authorized: true };
+
+/** Authorization was denied. */
+type Denied = {
+  authorized: false;
+  /** Reason for denial, included in the error message. */
+  reason?: string;
+};
+
+/** Result of an authorization hook evaluation. */
+export type UtilityCallAuthorizationResponse = Authorized | Denied;
+
+/**
+ * Hook called when a utility function attempts a cross-contract call.
+ * Returns a response indicating whether the call is authorized and an optional denial reason.
+ */
+export type AuthorizeUtilityCall = (
+  request: UtilityCallAuthorizationRequest,
+) => Promise<UtilityCallAuthorizationResponse>;

package/src/hooks/execution_hooks.ts

@@ -0,0 +1,68 @@
+import type { AuthorizeUtilityCall } from './authorize_utility_call.js';
+import type { ResolveCustomRequest } from './resolve_custom_request.js';
+import type { ResolveTaggingSecretStrategy } from './resolve_tagging_secret_strategy.js';
+
+/**
+ * Hooks that PXE invokes during client-side simulation to gate or steer operations that the protocol
+ * does not restrict on its own. They give the wallet a chance to apply custom policies (e.g.
+ * prompting the user, consulting a dynamic allowlist, or inspecting call arguments) before the
+ * execution proceeds. All hooks are optional, and when a hook is absent PXE applies a safe default.
+ *
+ * For example, {@link authorizeUtilityCall} is called whenever a utility function makes a cross-contract call. A call
+ * made by a malicious contract could leak private information, so the hook lets the wallet decide, per-call, whether
+ * to allow it. A static allowlist would not work here because neither the app nor the wallet can predict ahead of
+ * time which contracts will be invoked during execution. Calls to standard contracts (such as the HandshakeRegistry)
+ * bypass this hook and are always authorized. When the hook is absent, cross-contract utility calls are denied.
+ *
+ * Note: hooks are unrelated to authentication witnesses (authwits). Authwits are an on-chain
+ * mechanism where a contract verifies that a caller was authorized by a specific account; hooks
+ * are a client-side PXE concern that gates execution before it proceeds.
+ *
+ * @example
+ * ```ts
+ * const pxe = await PXE.create({
+ *   // ...
+ *   hooks: {
+ *     authorizeUtilityCall: async (req) => {
+ *       // Allow calls to a known helper contract, deny everything else.
+ *       return req.target.equals(trustedHelper)
+ *         ? { authorized: true }
+ *         : { authorized: false, reason: 'Unknown target' };
+ *     },
+ *     // Apply per-recipient policy: reach a known contact via their address keys (no onchain trace) and use a
+ *     // non-interactive handshake for everyone else.
+ *     resolveTaggingSecretStrategy: async ({ recipient }) =>
+ *       knownContacts.has(recipient.toString())
+ *         ? { type: 'address-derived' }
+ *         : { type: 'non-interactive-handshake' },
+ *   },
+ * });
+ * ```
+ */
+export interface ExecutionHooks {
+  /** Called when a contract attempts a cross-contract utility call. Calls are denied when absent. */
+  authorizeUtilityCall?: AuthorizeUtilityCall;
+  /**
+   * Resolves a message's tagging secret when none is already established for the sender/recipient pair, letting the
+   * wallet apply per-recipient policy. PXE applies a default when absent.
+   * See {@link ResolveTaggingSecretStrategy} for the request shape and defaults.
+   */
+  resolveTaggingSecretStrategy?: ResolveTaggingSecretStrategy;
+  /**
+   * Resolves a custom, caller-defined request a circuit cannot serve from local state. Any contract can issue one, so
+   * an implementor should verify both the request `kind` and the issuing contract (its address and class ID) before
+   * fulfilling it. Rejected when absent; see {@link ResolveCustomRequest}.
+   */
+  resolveCustomRequest?: ResolveCustomRequest;
+}
+
+/**
+ * Builds an {@link ExecutionHooks} from individually-constructed hook callbacks. Returns `undefined`
+ * when every field is absent, so callers can unconditionally pass the result as `hooks`.
+ */
+export function composeHooks(hooks: ExecutionHooks): ExecutionHooks | undefined {
+  if (Object.values(hooks).every(v => v === undefined)) {
+    return undefined;
+  }
+  return hooks;
+}

package/src/hooks/index.ts

@@ -0,0 +1,13 @@
+export type {
+  AuthorizeUtilityCall,
+  UtilityCallAuthorizationRequest,
+  UtilityCallAuthorizationResponse,
+} from './authorize_utility_call.js';
+export { type ExecutionHooks, composeHooks } from './execution_hooks.js';
+export { type CustomRequest, type ResolveCustomRequest } from './resolve_custom_request.js';
+export {
+  DEFAULT_TAGGING_SECRET_STRATEGY,
+  type ResolveTaggingSecretStrategy,
+  type TaggingSecretStrategy,
+  type TaggingSecretStrategyRequest,
+} from './resolve_tagging_secret_strategy.js';

package/src/hooks/resolve_custom_request.ts

@@ -0,0 +1,24 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+
+/**
+ * A custom, caller-defined request resolved via the {@link ResolveCustomRequest} hook. It carries no fixed meaning:
+ * `kind` selects the request type so one hook can serve many such types, and `payload` holds the opaque,
+ * request-specific arguments. The resolver answers by whatever means it needs (local state, a third party,
+ * offchain data).
+ */
+export type CustomRequest = {
+  /** The address of the contract issuing the request. */
+  contractAddress: AztecAddress;
+  /** The issuing contract's class ID, so resolvers can apply class-level (not just per-address) policy. */
+  contractClassId: Fr;
+  /** Discriminates the request type, letting one hook serve many such types. */
+  kind: Fr;
+  /** Opaque, request-specific arguments. */
+  payload: Fr[];
+};
+
+/**
+ * Hook resolving a {@link CustomRequest}. The resolver produces the response however it needs to.
+ */
+export type ResolveCustomRequest = (request: CustomRequest) => Promise<Fr[]>;