@aztec-labs/pxe 6.0.0-nightly.20260829

package/src/error_enriching.ts

@@ -0,0 +1,124 @@
+import type { Logger } from '@aztec-labs/foundation/log';
+import { allToCompletion } from '@aztec-labs/foundation/promise';
+import { resolveAssertionMessageFromRevertData, resolveOpcodeLocations } from '@aztec-labs/simulator/client';
+import { FunctionSelector } from '@aztec-labs/stdlib/abi';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import { type SimulationError, isNoirCallStackUnresolved } from '@aztec-labs/stdlib/errors';
+import type { BlockHeader } from '@aztec-labs/stdlib/tx';
+
+import type { ContractClassService } from './contract/contract_class_service.js';
+import type { ContractStore } from './storage/contract_store/contract_store.js';
+
+/**
+ * Adds contract and function names to a simulation error, if they
+ * can be found in the PXE database
+ * @param err - The error to enrich.
+ */
+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.
+  // eslint-disable-next-line aztec-custom/no-non-primitive-in-collections
+  const mentionedFunctions: Map<string, Set<FunctionSelector>> = new Map();
+
+  err.getCallStack().forEach(({ contractAddress, functionSelector }) => {
+    if (!mentionedFunctions.has(contractAddress.toString())) {
+      mentionedFunctions.set(contractAddress.toString(), new Set());
+    }
+    if (functionSelector) {
+      mentionedFunctions.get(contractAddress.toString())!.add(functionSelector);
+    }
+  });
+
+  await allToCompletion(
+    [...mentionedFunctions.entries()].map(async ([contractAddress, fnSelectors]) => {
+      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 allToCompletion(
+          artifact.functions.map(async fn => {
+            const selector = await FunctionSelector.fromNameAndParameters(fn);
+            selectorToNameMap.set(selector.toString(), fn.name);
+          }),
+        );
+
+        for (const fnSelector of fnSelectors) {
+          if (selectorToNameMap.has(fnSelector.toString())) {
+            err.enrichWithFunctionName(
+              parsedContractAddress,
+              fnSelector,
+              selectorToNameMap.get(fnSelector.toString())!,
+            );
+          } else {
+            logger.warn(
+              `Could not find function artifact in contract ${artifact.name} for function '${fnSelector}' when enriching error callstack`,
+            );
+          }
+        }
+      } else {
+        logger.warn(
+          `Could not find contract in database for address: ${parsedContractAddress} when enriching error callstack`,
+        );
+      }
+    }),
+  );
+}
+
+export async function enrichPublicSimulationError(
+  err: SimulationError,
+  contractStore: ContractStore,
+  contractClassService: ContractClassService,
+  anchorHeader: BlockHeader,
+  logger: Logger,
+) {
+  const callStack = err.getCallStack();
+  const originalFailingFunction = callStack[callStack.length - 1];
+
+  if (!originalFailingFunction) {
+    throw new Error(`Original failing function not found when enriching public simulation, missing callstack`);
+  }
+
+  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}.`,
+    );
+  }
+
+  const assertionMessage = resolveAssertionMessageFromRevertData(err.revertData, artifact);
+  if (assertionMessage) {
+    err.setOriginalMessage(err.getOriginalMessage() + `${assertionMessage}`);
+  }
+
+  const debugInfo = await contractStore.getPublicFunctionDebugMetadata(classId);
+
+  const noirCallStack = err.getNoirCallStack();
+  if (debugInfo) {
+    if (isNoirCallStackUnresolved(noirCallStack)) {
+      try {
+        // Public functions are simulated as a single Brillig entry point.
+        // Thus, we can safely assume here that the Brillig function id is `0`.
+        const parsedCallStack = resolveOpcodeLocations(noirCallStack, debugInfo.debugSymbols, debugInfo.files, 0);
+        err.setNoirCallStack(parsedCallStack);
+      } catch (err) {
+        logger.warn(
+          `Could not resolve noir call stack for ${originalFailingFunction.contractAddress.toString()}:${
+            originalFailingFunction.functionName?.toString() ?? ''
+          }: ${err}`,
+        );
+      }
+    }
+    await enrichSimulationError(err, contractStore, contractClassService, anchorHeader, logger);
+  }
+}

package/src/events/event_service.ts

@@ -0,0 +1,129 @@
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { createLogger } from '@aztec-labs/foundation/log';
+import { allToCompletion } from '@aztec-labs/foundation/promise';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import type { InBlock } from '@aztec-labs/stdlib/block';
+import { computePrivateEventCommitment, siloNullifier } from '@aztec-labs/stdlib/hash';
+import type { BlockHeader } from '@aztec-labs/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';
+import type { ChangeSetId } from '../storage/staged_write_coordinator.js';
+
+export class EventService {
+  constructor(
+    private readonly anchorBlockHeader: BlockHeader,
+    private readonly privateEventStore: PrivateEventStore,
+    private readonly changeSetId: ChangeSetId,
+    private readonly log = createLogger('pxe:event_service'),
+  ) {}
+
+  /**
+   * 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 allToCompletion(
+      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 = await siloNullifier(contractAddress, eventCommitment);
+
+    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 (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 = txData.nullifiers.findIndex(n => n.equals(siloedEventCommitment));
+    if (eventIndexInTx === -1) {
+      // 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(
+      selector,
+      randomness,
+      content,
+      siloedEventCommitment,
+      {
+        contractAddress,
+        scope,
+        txHash,
+        l2BlockNumber: txData.l2BlockNumber,
+        l2BlockHash: txData.l2BlockHash,
+        txIndexInBlock: txData.txIndexInBlock,
+        eventIndexInTx,
+      },
+      this.changeSetId,
+    );
+  }
+}
+
+/** 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/index.ts

@@ -0,0 +1 @@
+export * from './private_event_filter_validator.js';

package/src/events/private_event_filter_validator.ts

@@ -0,0 +1,66 @@
+import type { PrivateEventFilter } from '@aztec-labs/aztec.js/wallet';
+import { INITIAL_L2_BLOCK_NUM } from '@aztec-labs/constants';
+import { BlockNumber } from '@aztec-labs/foundation/branded-types';
+import { createLogger } from '@aztec-labs/foundation/log';
+
+import type { PrivateEventStoreFilter } from '../storage/private_event_store/private_event_store.js';
+
+export class PrivateEventFilterValidator {
+  private readonly log = createLogger('pxe:private_event_filter_validator');
+
+  constructor(private readonly lastBlock: BlockNumber) {}
+
+  validate(filter: PrivateEventFilter): PrivateEventStoreFilter {
+    let { fromBlock, toBlock } = filter;
+
+    // Block range filters in Aztec Node are defined as closed-open intervals [fromBlock, toBlock), so
+    // we respect that convention here for consistency.
+    // We then default to [INITIAL_L2_BLOCK_NUM, latestKnownBlock + 1), ie: by default return events from
+    // the first block to the latest known block.
+    if (!fromBlock || !toBlock) {
+      fromBlock = fromBlock ?? BlockNumber(INITIAL_L2_BLOCK_NUM);
+      toBlock = toBlock ?? BlockNumber(this.lastBlock + 1);
+    }
+
+    if (filter.scopes.length === 0) {
+      throw new Error('At least one scope is required to get private events');
+    }
+
+    if (fromBlock < 1) {
+      throw new Error('fromBlock must be greater than or equal to 1');
+    }
+
+    if (toBlock < 1) {
+      throw new Error('toBlock must be greater than or equal to 1');
+    }
+
+    if (fromBlock >= toBlock) {
+      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,
+      txHash: filter.txHash,
+      toBlock,
+      fromBlock,
+    };
+  }
+}

package/src/hooks/authorize_utility_call.ts

@@ -0,0 +1,44 @@
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { FunctionSelector } from '@aztec-labs/stdlib/abi';
+import type { AztecAddress } from '@aztec-labs/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-labs/foundation/curves/bn254';
+import type { AztecAddress } from '@aztec-labs/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-labs/foundation/curves/bn254';
+import type { Point } from '@aztec-labs/foundation/curves/grumpkin';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import type { AppTaggingSecretKind } from '@aztec-labs/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>;