@aztec/stdlib 5.0.0-private.20260319 → 5.0.0-rc.1

package/src/interfaces/aztec-node-admin.ts

@@ -1,9 +1,11 @@
+import type { L1ContractAddresses } from '@aztec/ethereum/l1-contract-addresses';
 import { createSafeJsonRpcClient, defaultFetch } from '@aztec/foundation/json-rpc/client';
 
 import { z } from 'zod';
 
 import type { ApiSchemaFor } from '../schemas/schemas.js';
-import { type Offense, OffenseSchema, type SlashPayloadRound, SlashPayloadRoundSchema } from '../slashing/index.js';
+import { optional } from '../schemas/schemas.js';
+import { type Offense, OffenseSchema } from '../slashing/index.js';
 import { type ComponentsVersions, getVersioningResponseHandler } from '../versioning/index.js';
 import { type ArchiverSpecificConfig, ArchiverSpecificConfigSchema } from './archiver.js';
 import { type SequencerConfig, SequencerConfigSchema } from './configs.js';
@@ -36,8 +38,9 @@ export interface AztecNodeAdmin {
    * Pauses syncing and rolls back the database to the target L2 block number.
    * @param targetBlockNumber - The block number to roll back to.
    * @param force - If true, clears the world state db and p2p dbs if rolling back to behind the finalized block.
+   * @param resumeSync - If true (default), resumes archiver and world state sync after rollback.
    */
-  rollbackTo(targetBlockNumber: number, force?: boolean): Promise<void>;
+  rollbackTo(targetBlockNumber: number, force?: boolean, resumeSync?: boolean): Promise<void>;
 
   /** Pauses archiver and world state syncing. */
   pauseSync(): Promise<void>;
@@ -45,8 +48,14 @@ export interface AztecNodeAdmin {
   /** Resumes archiver and world state syncing. */
   resumeSync(): Promise<void>;
 
-  /** Returns all monitored payloads by the slasher for the current round. */
-  getSlashPayloads(): Promise<SlashPayloadRound[]>;
+  /**
+   * Pauses block production. Pending txs remain in the mempool; no new blocks will be
+   * produced until {@link resumeSequencer} is called. Throws if no sequencer is running.
+   */
+  pauseSequencer(): Promise<void>;
+
+  /** Resumes block production previously paused via {@link pauseSequencer}. */
+  resumeSequencer(): Promise<void>;
 
   /** Returns all offenses applicable for the given round. */
   getSlashOffenses(round: bigint | 'all' | 'current'): Promise<Offense[]>;
@@ -72,8 +81,8 @@ export interface AztecNodeAdmin {
   reloadKeystore(): Promise<void>;
 }
 
-// L1 contracts are not mutable via admin updates.
-export type AztecNodeAdminConfig = Omit<ValidatorClientFullConfig, 'l1Contracts'> &
+// L1 contract addresses are pinned at startup and are not mutable via admin updates.
+export type AztecNodeAdminConfig = Omit<ValidatorClientFullConfig, keyof L1ContractAddresses> &
   SequencerConfig &
   ProverConfig &
   SlasherConfig &
@@ -82,11 +91,13 @@ export type AztecNodeAdminConfig = Omit<ValidatorClientFullConfig, 'l1Contracts'
     'archiverPollingIntervalMS' | 'archiverBatchSize' | 'skipValidateCheckpointAttestations'
   > & {
     maxPendingTxCount: number;
+    // Keep in sync with P2PConfig.skipIncomingProposals (circular dep prevents Pick<P2PConfig, ...> here)
+    skipIncomingProposals?: boolean;
   };
 
 export const AztecNodeAdminConfigSchema = SequencerConfigSchema.merge(ProverConfigSchema)
   .merge(SlasherConfigSchema)
-  .merge(ValidatorClientFullConfigSchema.omit({ l1Contracts: true }))
+  .merge(ValidatorClientFullConfigSchema.omit({ rollupAddress: true }))
   .merge(
     ArchiverSpecificConfigSchema.pick({
       archiverPollingIntervalMS: true,
@@ -94,21 +105,25 @@ export const AztecNodeAdminConfigSchema = SequencerConfigSchema.merge(ProverConf
       skipValidateCheckpointAttestations: true,
     }),
   )
-  .merge(z.object({ maxPendingTxCount: z.number() }));
+  .merge(z.object({ maxPendingTxCount: z.number(), skipIncomingProposals: z.boolean().optional() }));
 
 export const AztecNodeAdminApiSchema: ApiSchemaFor<AztecNodeAdmin> = {
-  getConfig: z.function().returns(AztecNodeAdminConfigSchema),
-  setConfig: z.function().args(AztecNodeAdminConfigSchema.partial()).returns(z.void()),
-  startSnapshotUpload: z.function().args(z.string()).returns(z.void()),
-  rollbackTo: z.function().args(z.number()).returns(z.void()),
-  pauseSync: z.function().returns(z.void()),
-  resumeSync: z.function().returns(z.void()),
-  getSlashPayloads: z.function().returns(z.array(SlashPayloadRoundSchema)),
-  getSlashOffenses: z
-    .function()
-    .args(z.union([z.bigint(), z.literal('all'), z.literal('current')]))
-    .returns(z.array(OffenseSchema)),
-  reloadKeystore: z.function().returns(z.void()),
+  getConfig: z.function({ input: z.tuple([]), output: AztecNodeAdminConfigSchema }),
+  setConfig: z.function({ input: z.tuple([AztecNodeAdminConfigSchema.partial()]), output: z.void() }),
+  startSnapshotUpload: z.function({ input: z.tuple([z.string()]), output: z.void() }),
+  rollbackTo: z.function({
+    input: z.tuple([z.number(), optional(z.boolean()), optional(z.boolean())]),
+    output: z.void(),
+  }),
+  pauseSync: z.function({ input: z.tuple([]), output: z.void() }),
+  resumeSync: z.function({ input: z.tuple([]), output: z.void() }),
+  pauseSequencer: z.function({ input: z.tuple([]), output: z.void() }),
+  resumeSequencer: z.function({ input: z.tuple([]), output: z.void() }),
+  getSlashOffenses: z.function({
+    input: z.tuple([z.union([z.bigint(), z.literal('all'), z.literal('current')])]),
+    output: z.array(OffenseSchema),
+  }),
+  reloadKeystore: z.function({ input: z.tuple([]), output: z.void() }),
 };
 
 export function createAztecNodeAdminClient(
@@ -118,7 +133,7 @@ export function createAztecNodeAdminClient(
   apiKey?: string,
 ): AztecNodeAdmin {
   return createSafeJsonRpcClient<AztecNodeAdmin>(url, AztecNodeAdminApiSchema, {
-    namespaceMethods: 'nodeAdmin',
+    namespaceMethods: 'aztecAdmin',
     fetch,
     onResponse: getVersioningResponseHandler(versions),
     ...(apiKey ? { extraHeaders: { 'x-api-key': apiKey } } : {}),

package/src/interfaces/aztec-node-debug.ts

@@ -0,0 +1,55 @@
+import { type CheckpointNumber, CheckpointNumberSchema } from '@aztec/foundation/branded-types';
+import { createSafeJsonRpcClient, defaultFetch } from '@aztec/foundation/json-rpc/client';
+
+import { z } from 'zod';
+
+import { type ApiSchemaFor, optional } from '../schemas/schemas.js';
+import { type ComponentsVersions, getVersioningResponseHandler } from '../versioning/index.js';
+
+/**
+ * Debug interface for Aztec node available in sandbox/local-network mode.
+ */
+export interface AztecNodeDebug {
+  /**
+   * Triggers the sequencer to produce an L2 block and waits for it to appear.
+   *
+   * **Precondition**: The current L2 slot must not already contain a block. Callers must ensure L1 time has been
+   * advanced to a slot with no existing block before calling this method (e.g. via `EthCheatCodes.warp()`).
+   * If the slot is already taken, the sequencer will fail to propose and this call will time out.
+   *
+   * @throws If no sequencer is running.
+   */
+  mineBlock(): Promise<void>;
+
+  /**
+   * Synthetically proves the L2 chain up to the given checkpoint (default: the latest checkpointed
+   * checkpoint), writing epoch out hashes into the L1 Outbox so L2-to-L1 messages become consumable
+   * and advancing the rollup's proven tip. There is no real proof — this is the local-network
+   * equivalent of an epoch proof landing on L1. The target is clamped to the latest checkpointed
+   * checkpoint and the call no-ops when it is already proven.
+   *
+   * @param upToCheckpoint - Checkpoint to prove up to; defaults to the latest checkpointed checkpoint.
+   * @returns The proven checkpoint number after the call.
+   * @throws If no automine sequencer is running (only the automine sequencer supports synthetic proving).
+   */
+  prove(upToCheckpoint?: CheckpointNumber): Promise<CheckpointNumber>;
+}
+
+export const AztecNodeDebugApiSchema: ApiSchemaFor<AztecNodeDebug> = {
+  mineBlock: z.function({ input: z.tuple([]), output: z.void() }),
+  prove: z.function({ input: z.tuple([optional(CheckpointNumberSchema)]), output: CheckpointNumberSchema }),
+};
+
+export function createAztecNodeDebugClient(
+  url: string,
+  versions: Partial<ComponentsVersions> = {},
+  fetch = defaultFetch,
+  apiKey?: string,
+): AztecNodeDebug {
+  return createSafeJsonRpcClient<AztecNodeDebug>(url, AztecNodeDebugApiSchema, {
+    namespaceMethods: 'aztecDebug',
+    fetch,
+    onResponse: getVersioningResponseHandler(versions),
+    ...(apiKey ? { extraHeaders: { 'x-api-key': apiKey } } : {}),
+  });
+}