@aztec/pxe 0.0.1-commit.03f7ef2 → 0.0.1-commit.04d373f

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,48 @@
+import type { AuthorizeUtilityCall } from './authorize_utility_call.js';
+
+/**
+ * Hooks that PXE invokes during client-side simulation to gate 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.
+ *
+ * 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.
+ *
+ * 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' };
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export interface ExecutionHooks {
+  /** Called when a contract attempts a cross-contract utility call. */
+  authorizeUtilityCall: AuthorizeUtilityCall;
+}
+
+/**
+ * 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)) {
+    return undefined;
+  }
+  return partial as ExecutionHooks;
+}

package/src/hooks/index.ts

@@ -0,0 +1,7 @@
+export type {
+  AuthorizeUtilityCall,
+  UtilityCallAuthorizationRequest,
+  UtilityCallAuthorizationResponse,
+} from './authorize_utility_call.js';
+export type { ExecutionHooks } from './execution_hooks.js';
+export { composeHooks } from './execution_hooks.js';

package/src/job_coordinator/job_coordinator.ts

@@ -0,0 +1,150 @@
+import { randomBytes } from '@aztec/foundation/crypto/random';
+import { type Logger, type LoggerBindings, createLogger } from '@aztec/foundation/log';
+import type { AztecAsyncKVStore } from '@aztec/kv-store';
+
+/**
+ * Interface that stores must implement to support staged writes.
+ */
+export interface StagedStore {
+  /** Unique name identifying this store (used for tracking staged stores from JobCoordinator) */
+  readonly storeName: string;
+
+  /**
+   * Commits staged data to main storage.
+   * Should be called within a transaction for atomicity.
+   *
+   * @param jobId - The job identifier
+   */
+  commit(jobId: string): Promise<void>;
+
+  /**
+   * Discards staged data without committing.
+   * Called on abort.
+   *
+   * @param jobId - The job identifier
+   */
+  discardStaged(jobId: string): Promise<void>;
+}
+
+/**
+ * JobCoordinator manages job lifecycle and provides crash resilience for PXE operations.
+ *
+ * It uses a staged writes pattern:
+ * 1. When a job begins, a unique job ID is created
+ * 2. During the job, all writes go to staging (keyed by job ID)
+ * 3. On commit, staging is promoted to main storage
+ * 4. On abort, staged data is discarded
+ *
+ * Note: PXE should only rely on a single JobCoordinator instance, so it can eventually
+ * orchestrate concurrent jobs. Right now it doesn't make a difference because we're
+ * using a job queue with concurrency=1.
+ */
+export class JobCoordinator {
+  private readonly log: Logger;
+
+  /** The underlying KV store */
+  kvStore: AztecAsyncKVStore;
+
+  #currentJobId: string | undefined;
+  #stores: Map<string, StagedStore> = new Map();
+
+  constructor(kvStore: AztecAsyncKVStore, bindings?: LoggerBindings) {
+    this.kvStore = kvStore;
+    this.log = createLogger('pxe:job_coordinator', bindings);
+  }
+
+  /**
+   * Registers a staged store.
+   * Must be called during initialization for all stores that need staging support.
+   */
+  registerStore(store: StagedStore): void {
+    if (this.#stores.has(store.storeName)) {
+      throw new Error(`Store "${store.storeName}" is already registered`);
+    }
+    this.#stores.set(store.storeName, store);
+    this.log.debug(`Registered staged store: ${store.storeName}`);
+  }
+
+  /**
+   * Registers multiple staged stores.
+   */
+  registerStores(stores: StagedStore[]): void {
+    for (const store of stores) {
+      this.registerStore(store);
+    }
+  }
+
+  /**
+   * Begins a new job and returns a job ID for staged writes.
+   *
+   * @returns Job ID to pass to store operations
+   */
+  beginJob(): string {
+    if (this.#currentJobId) {
+      throw new Error(
+        `Cannot begin job: job ${this.#currentJobId} is already in progress. ` +
+          `This should not happen - ensure jobs are properly committed or aborted.`,
+      );
+    }
+
+    const jobId = randomBytes(8).toString('hex');
+    this.#currentJobId = jobId;
+
+    this.log.debug(`Started job ${jobId}`);
+    return jobId;
+  }
+
+  /**
+   * Commits a job by promoting all staged data to main storage.
+   *
+   * @param jobId - The job ID returned from beginJob
+   */
+  async commitJob(jobId: string): Promise<void> {
+    if (!this.#currentJobId || this.#currentJobId !== jobId) {
+      throw new Error(
+        `Cannot commit job ${jobId}: no matching job in progress. ` + `Current job: ${this.#currentJobId ?? 'none'}`,
+      );
+    }
+
+    this.log.debug(`Committing job ${jobId}`);
+
+    // Commit all stores atomically in a single transaction.
+    // Each store's commit is a no-op if it has no staged data (but that's up to each store to handle).
+    await this.kvStore.transactionAsync(async () => {
+      for (const store of this.#stores.values()) {
+        await store.commit(jobId);
+      }
+    });
+
+    this.#currentJobId = undefined;
+    this.log.debug(`Job ${jobId} committed successfully`);
+  }
+
+  /**
+   * Aborts a job by discarding all staged data.
+   *
+   * @param jobId - The job ID returned from beginJob
+   */
+  async abortJob(jobId: string): Promise<void> {
+    if (!this.#currentJobId || this.#currentJobId !== jobId) {
+      // Job may have already been aborted or never started properly
+      this.log.warn(`Abort called for job ${jobId} but current job is ${this.#currentJobId ?? 'none'}`);
+    }
+
+    this.log.debug(`Aborting job ${jobId}`);
+
+    for (const store of this.#stores.values()) {
+      await store.discardStaged(jobId);
+    }
+
+    this.#currentJobId = undefined;
+    this.log.debug(`Job ${jobId} aborted`);
+  }
+
+  /**
+   * Checks if there's a job currently in progress.
+   */
+  hasJobInProgress(): boolean {
+    return this.#currentJobId !== undefined;
+  }
+}