@aztec/pxe 0.0.1-commit.2f68f620 → 0.0.1-commit.3100065

package/src/contract_function_simulator/transient_array_service.ts

@@ -0,0 +1,91 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+
+/**
+ * In-memory store for transient arrays.
+ *
+ * Unlike {@link EphemeralArrayService} (one instance per call frame), a single `TransientArrayService` instance is shared
+ * across all frames of one top-level PXE call (a transaction simulation or utility call), so arrays survive across nested
+ * private and utility calls. Entries are keyed by `(contract address, slot)`; the contract address is supplied by the
+ * oracle from its execution context, so a contract can only ever name its own arrays. The store is purely in-memory and
+ * is discarded when the top-level PXE call completes — it is never persisted.
+ */
+export class TransientArrayService {
+  /** Maps a `(contract address, slot)` key to the serialized elements stored there. */
+  #arrays: Map<string, Fr[][]> = new Map();
+
+  #key(contractAddress: AztecAddress, slot: Fr): string {
+    return `${contractAddress.toString()}:${slot.toString()}`;
+  }
+
+  /** Returns all elements at the given key, or an empty array if uninitialized. */
+  readArrayAt(contractAddress: AztecAddress, slot: Fr): Fr[][] {
+    return this.#arrays.get(this.#key(contractAddress, slot)) ?? [];
+  }
+
+  #setArray(contractAddress: AztecAddress, slot: Fr, array: Fr[][]): void {
+    this.#arrays.set(this.#key(contractAddress, slot), array);
+  }
+
+  /** Returns the number of elements stored at the given key. */
+  len(contractAddress: AztecAddress, slot: Fr): number {
+    return this.readArrayAt(contractAddress, slot).length;
+  }
+
+  /** Appends an element and returns the new length. */
+  push(contractAddress: AztecAddress, slot: Fr, elements: Fr[]): number {
+    const array = this.readArrayAt(contractAddress, slot);
+    array.push(elements);
+    this.#setArray(contractAddress, slot, array);
+    return array.length;
+  }
+
+  /** Removes and returns the last element. Throws if empty. */
+  pop(contractAddress: AztecAddress, slot: Fr): Fr[] {
+    const array = this.readArrayAt(contractAddress, slot);
+    if (array.length === 0) {
+      throw new Error(`Transient array at slot ${slot} is empty`);
+    }
+    const element = array.pop()!;
+    this.#setArray(contractAddress, slot, array);
+    return element;
+  }
+
+  /** Returns the element at the given index. Throws if out of bounds. */
+  get(contractAddress: AztecAddress, slot: Fr, index: number): Fr[] {
+    const array = this.readArrayAt(contractAddress, slot);
+    if (index < 0 || index >= array.length) {
+      throw new Error(
+        `Transient array index ${index} out of bounds for array of length ${array.length} at slot ${slot}`,
+      );
+    }
+    return array[index];
+  }
+
+  /** Overwrites the element at the given index. Throws if out of bounds. */
+  set(contractAddress: AztecAddress, slot: Fr, index: number, value: Fr[]): void {
+    const array = this.readArrayAt(contractAddress, slot);
+    if (index < 0 || index >= array.length) {
+      throw new Error(
+        `Transient array index ${index} out of bounds for array of length ${array.length} at slot ${slot}`,
+      );
+    }
+    array[index] = value;
+  }
+
+  /** Removes the element at the given index, shifting subsequent elements backward. Throws if out of bounds. */
+  remove(contractAddress: AztecAddress, slot: Fr, index: number): void {
+    const array = this.readArrayAt(contractAddress, slot);
+    if (index < 0 || index >= array.length) {
+      throw new Error(
+        `Transient array index ${index} out of bounds for array of length ${array.length} at slot ${slot}`,
+      );
+    }
+    array.splice(index, 1);
+  }
+
+  /** Removes all elements at the given key. */
+  clear(contractAddress: AztecAddress, slot: Fr): void {
+    this.#arrays.delete(this.#key(contractAddress, slot));
+  }
+}

package/src/debug/pxe_debug_utils.ts

@@ -5,8 +5,8 @@ import type { NoteDao } from '@aztec/stdlib/note';
 import type { ContractOverrides } from '@aztec/stdlib/tx';
 
 import type { BlockSynchronizer } from '../block_synchronizer/block_synchronizer.js';
+import type { ContractSyncService } from '../contract/contract_sync_service.js';
 import type { ContractFunctionSimulator } from '../contract_function_simulator/contract_function_simulator.js';
-import type { ContractSyncService } from '../contract_sync/contract_sync_service.js';
 import type { NotesFilter } from '../notes_filter.js';
 import type { AnchorBlockStore } from '../storage/index.js';
 import type { NoteStore } from '../storage/note_store/note_store.js';

package/src/entrypoints/client/bundle/utils.ts

@@ -1,8 +1,10 @@
 import { BBBundlePrivateKernelProver } from '@aztec/bb-prover/client/bundle';
 import { createLogger } from '@aztec/foundation/log';
-import { createStore } from '@aztec/kv-store/indexeddb';
+import { createStore } from '@aztec/kv-store/sqlite-opfs';
 import { BundledProtocolContractsProvider } from '@aztec/protocol-contracts/providers/bundle';
 import { WASMSimulator } from '@aztec/simulator/client';
+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';
 
@@ -35,7 +37,7 @@ export async function createPXE(
     ...l1ContractAddresses,
   } as PXEConfig;
 
-  const storeLogger = loggers.store ?? createLogger('pxe:data:idb', { actor });
+  const storeLogger = loggers.store ?? createLogger('pxe:data', { actor });
 
   const store =
     options.store ?? (await createStore('pxe_data', configWithContracts, PXE_DATA_SCHEMA_VERSION, storeLogger));
@@ -51,12 +53,17 @@ export async function createPXE(
   }
   const protocolContractsProvider = new BundledProtocolContractsProvider();
   const preloadedContractsProvider = options.preloadedContractsProvider ?? {
-    getPreloadedContracts: async () => [await getStandardMultiCallEntrypoint()],
+    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,
     proofCreator: prover,
     simulator,

package/src/entrypoints/client/lazy/utils.ts

@@ -1,8 +1,10 @@
 import { BBLazyPrivateKernelProver } from '@aztec/bb-prover/client/lazy';
 import { createLogger } from '@aztec/foundation/log';
-import { createStore } from '@aztec/kv-store/indexeddb';
+import { createStore } from '@aztec/kv-store/sqlite-opfs';
 import { LazyProtocolContractsProvider } from '@aztec/protocol-contracts/providers/lazy';
 import { WASMSimulator } from '@aztec/simulator/client';
+import { getStandardAuthRegistry } from '@aztec/standard-contracts/auth-registry/lazy';
+import { getStandardHandshakeRegistry } from '@aztec/standard-contracts/handshake-registry/lazy';
 import { getStandardMultiCallEntrypoint } from '@aztec/standard-contracts/multi-call-entrypoint/lazy';
 import type { AztecNode } from '@aztec/stdlib/interfaces/client';
 
@@ -35,7 +37,7 @@ export async function createPXE(
 
   const loggers = options.loggers ?? {};
 
-  const storeLogger = loggers.store ?? createLogger('pxe:data:idb', { actor });
+  const storeLogger = loggers.store ?? createLogger('pxe:data', { actor });
 
   const store =
     options.store ?? (await createStore('pxe_data', configWithContracts, PXE_DATA_SCHEMA_VERSION, storeLogger));
@@ -51,12 +53,17 @@ export async function createPXE(
   }
   const protocolContractsProvider = new LazyProtocolContractsProvider();
   const preloadedContractsProvider = options.preloadedContractsProvider ?? {
-    getPreloadedContracts: async () => [await getStandardMultiCallEntrypoint()],
+    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,
     proofCreator: prover,
     simulator,

package/src/entrypoints/pxe_creation_options.ts

@@ -2,7 +2,7 @@ import type { BBPrivateKernelProverOptions } from '@aztec/bb-prover/client';
 import type { Logger } from '@aztec/foundation/log';
 import type { AztecAsyncKVStore } from '@aztec/kv-store';
 import type { CircuitSimulator } from '@aztec/simulator/client';
-import type { PrivateKernelProver } from '@aztec/stdlib/interfaces/client';
+import type { AztecNodeDebug, PrivateKernelProver } from '@aztec/stdlib/interfaces/client';
 
 import type { ExecutionHooks } from '../hooks/index.js';
 import type { PreloadedContractsProvider } from '../pxe.js';
@@ -16,8 +16,14 @@ export type PXECreationOptions = {
   simulator?: CircuitSimulator;
   /** Optional hooks to observe and influence contract execution. */
   hooks?: ExecutionHooks;
-  /** Contracts to preload; used directly in place of the PXE's default (the standard multi-call entrypoint). */
+  /** Contracts to preload on startup. Replaces the default when set. */
   preloadedContractsProvider?: PreloadedContractsProvider;
+  /**
+   * Optional debug API client for the same node. When provided, public function signatures are registered so the
+   * node can produce named public-execution stack traces. Only available on nodes started with debug endpoints
+   * enabled; omitted in prod-like setups.
+   */
+  nodeDebug?: AztecNodeDebug;
 };
 
 /** Checks if the given value implements the PrivateKernelProver interface via duck-typing. */

package/src/entrypoints/server/index.ts

@@ -1,6 +1,7 @@
+export { type AccountPrivacyKeys, type AccountPrivacySecretKeys } from '@aztec/key-store';
+
 export * from '../../notes_filter.js';
 export * from '../../pxe.js';
-export * from '../../hooks/index.js';
 export * from '../../config/index.js';
 export * from '../../error_enriching.js';
 export * from '../../storage/index.js';
@@ -9,4 +10,6 @@ export { NoteService } from '../../notes/note_service.js';
 export { ORACLE_VERSION_MAJOR, ORACLE_VERSION_MINOR } from '../../oracle_version.js';
 export { type PXECreationOptions } from '../pxe_creation_options.js';
 export { JobCoordinator } from '../../job_coordinator/job_coordinator.js';
-export { ContractSyncService } from '../../contract_sync/contract_sync_service.js';
+export { ContractSyncService } from '../../contract/contract_sync_service.js';
+export { ContractClassService } from '../../contract/contract_class_service.js';
+export { AnchoredContractData } from '../../contract_function_simulator/anchored_contract_data.js';

package/src/entrypoints/server/utils.ts

@@ -3,8 +3,11 @@ import type { L1ContractAddresses } from '@aztec/ethereum/l1-contract-addresses'
 import { createLogger } from '@aztec/foundation/log';
 import { createStore } 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';
 
@@ -61,12 +64,17 @@ export async function createPXE(
 
   const protocolContractsProvider = new BundledProtocolContractsProvider();
   const preloadedContractsProvider = options.preloadedContractsProvider ?? {
-    getPreloadedContracts: async () => [await getStandardMultiCallEntrypoint()],
+    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,

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/hooks/execution_hooks.ts

@@ -1,16 +1,18 @@
 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 operations that the protocol
+ * 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.
+ * 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.
+ * 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
@@ -27,22 +29,40 @@ import type { AuthorizeUtilityCall } from './authorize_utility_call.js';
  *         ? { 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. */
-  authorizeUtilityCall: AuthorizeUtilityCall;
+  /** 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(partial: Partial<ExecutionHooks>): ExecutionHooks | undefined {
-  if (Object.values(partial).every(v => v === undefined)) {
+export function composeHooks(hooks: ExecutionHooks): ExecutionHooks | undefined {
+  if (Object.values(hooks).every(v => v === undefined)) {
     return undefined;
   }
-  return partial as ExecutionHooks;
+  return hooks;
 }

package/src/hooks/index.ts

@@ -3,5 +3,11 @@ export type {
   UtilityCallAuthorizationRequest,
   UtilityCallAuthorizationResponse,
 } from './authorize_utility_call.js';
-export type { ExecutionHooks } from './execution_hooks.js';
-export { composeHooks } from './execution_hooks.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>;