@aztec/pxe 0.0.1-commit.c2eed6949 → 0.0.1-commit.c52d6e7

package/src/entrypoints/server/utils.ts

@@ -1,18 +1,26 @@
-import { BBPrivateKernelProver } from '@aztec/bb-prover/client';
 import { BBBundlePrivateKernelProver } from '@aztec/bb-prover/client/bundle';
+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,
@@ -28,10 +36,10 @@ export async function createPXE(
   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,
@@ -39,33 +47,56 @@ export async function createPXE(
 
   if (!options.store) {
     const storeLogger = loggers.store ?? createLogger('pxe:data:lmdb', { actor });
-    options.store = await createStore(
-      'pxe_data',
-      PXE_DATA_SCHEMA_VERSION,
-      configWithContracts,
-      storeLogger.getBindings(),
-    );
+    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 ?? 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 ?? createLogger('pxe:service', { actor });
   const pxe = await PXE.create({
     node: aztecNode,
+    nodeDebug: options.nodeDebug,
     store: options.store,
     proofCreator: prover,
     simulator,
     protocolContractsProvider,
+    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,10 +1,12 @@
 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 type { InBlock } from '@aztec/stdlib/block';
+import { computePrivateEventCommitment, siloNullifier } from '@aztec/stdlib/hash';
 import type { AztecNode } from '@aztec/stdlib/interfaces/server';
-import type { BlockHeader, TxHash } from '@aztec/stdlib/tx';
+import type { BlockHeader } from '@aztec/stdlib/tx';
 
+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 {
@@ -13,42 +15,92 @@ export class EventService {
     private readonly aztecNode: AztecNode,
     private readonly privateEventStore: PrivateEventStore,
     private readonly jobId: string,
+    private readonly log = createLogger('pxe:event_service'),
   ) {}
 
-  public async validateAndStoreEvent(
-    contractAddress: AztecAddress,
-    selector: EventSelector,
-    randomness: Fr,
-    content: Fr[],
-    eventCommitment: Fr,
-    txHash: TxHash,
+  /**
+   * Validates and stores a batch of private events against the pre-fetched onchain context of their txs.
+   *
+   * @param requests - The events to validate and store.
+   * @param scope - The scope under which the events are being stored.
+   * @param validationTxData - The onchain context of each request's tx, 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,
+    validationTxData: ReadonlyMap<string, EventValidationTxData>,
   ): Promise<void> {
+    if (requests.length === 0) {
+      return;
+    }
+
+    const anchorBlockNumber = this.anchorBlockHeader.getBlockNumber();
+
+    await Promise.all(
+      requests.map(req => this.#validateAndStoreEvent(req, scope, validationTxData, anchorBlockNumber)),
+    );
+  }
+
+  async #validateAndStoreEvent(
+    request: EventValidationRequest,
+    scope: AztecAddress,
+    validationTxData: ReadonlyMap<string, EventValidationTxData>,
+    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 [siloedEventCommitment, txEffect] = await Promise.all([
-      siloNullifier(contractAddress, eventCommitment),
-      this.aztecNode.getTxEffect(txHash),
-    ]);
-
-    const anchorBlockNumber = this.anchorBlockHeader.getBlockNumber();
+    const siloedEventCommitment = await siloNullifier(contractAddress, eventCommitment);
 
-    if (!txEffect) {
-      throw new Error(`Could not find tx effect for tx hash ${txHash}`);
+    const txData = validationTxData.get(txHash.toString());
+    if (!txData) {
+      // 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}`);
+    if (txData.l2BlockNumber > 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));
+    const eventIndexInTx = txData.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(
@@ -60,12 +112,18 @@ export class EventService {
         contractAddress,
         scope,
         txHash,
-        l2BlockNumber: txEffect.l2BlockNumber,
-        l2BlockHash: txEffect.l2BlockHash,
-        txIndexInBlock: txEffect.txIndexInBlock,
+        l2BlockNumber: txData.l2BlockNumber,
+        l2BlockHash: txData.l2BlockHash,
+        txIndexInBlock: txData.txIndexInBlock,
         eventIndexInTx,
       },
       this.jobId,
     );
   }
 }
+
+/** The onchain context of the tx an event validation request points at: where it was mined and its nullifiers. */
+export type EventValidationTxData = InBlock & {
+  nullifiers: Fr[];
+  txIndexInBlock: number;
+};

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[]>;

package/src/hooks/resolve_tagging_secret_strategy.ts

@@ -0,0 +1,60 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { Point } from '@aztec/foundation/curves/grumpkin';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { AppTaggingSecretKind } from '@aztec/stdlib/logs';
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- only referenced by a {@link} doc tag
+import type { ResolveCustomRequest } from './resolve_custom_request.js';
+
+/**
+ * How a message's tagging secret is chosen: the wallet's strategy, returned by the `resolveTaggingSecretStrategy` hook
+ * when no onchain handshake has been registered for the sender/recipient pair. This is intent (plus, for an arbitrary
+ * secret, the raw material); PXE resolves it into the secret it hands the contract.
+ */
+export type TaggingSecretStrategy =
+  | {
+      /** Establish a fresh non-interactive handshake via the onchain registry; reveals the recipient onchain. */
+      type: 'non-interactive-handshake';
+    }
+  | {
+      /**
+       * Establish a fresh interactive handshake via the onchain registry. Reveals nothing about the recipient
+       * onchain, but requires the recipient to answer the registry's signed-authorization request (served through
+       * the {@link ResolveCustomRequest} hook), so the send fails when it cannot be served.
+       */
+      type: 'interactive-handshake';
+    }
+  | {
+      /** Derive the secret from the sender's and recipient's address keys via ECDH. PXE computes and silos it. */
+      type: 'address-derived';
+    }
+  | {
+      /**
+       * A raw shared secret point the two parties already share offchain (e.g. coordinated out-of-band), supplied by
+       * the wallet. PXE app-silos it before use. Only sound for unconstrained delivery, since nothing onchain proves
+       * the recipient knows it.
+       */
+      type: 'arbitrary-secret';
+      /** The raw (un-siloed) shared secret point to derive the tag from. */
+      secret: Point;
+    };
+
+/** The strategy PXE applies to both delivery modes when no `resolveTaggingSecretStrategy` hook is configured. */
+export const DEFAULT_TAGGING_SECRET_STRATEGY: TaggingSecretStrategy = { type: 'non-interactive-handshake' };
+
+/** Information about the message delivery requesting a tagging secret strategy. */
+export type TaggingSecretStrategyRequest = {
+  contractAddress: AztecAddress;
+  /**
+   * The contract class ID of the executing contract, so wallets can apply class-level (not just per-address) policy.
+   */
+  contractClassId: Fr;
+  sender: AztecAddress;
+  recipient: AztecAddress;
+  deliveryMode: AppTaggingSecretKind;
+};
+
+/**
+ * Hook returning the {@link TaggingSecretStrategy} for an outgoing message.
+ */
+export type ResolveTaggingSecretStrategy = (request: TaggingSecretStrategyRequest) => Promise<TaggingSecretStrategy>;