@aztec/stdlib 0.0.1-commit.64b6bbb → 0.0.1-commit.69c59a8b3

package/src/ha-signing/types.ts

@@ -0,0 +1,126 @@
+import {
+  BlockNumber,
+  CheckpointNumber,
+  type IndexWithinCheckpoint,
+  type SlotNumber,
+} from '@aztec/foundation/branded-types';
+
+/**
+ * Type of validator duty being performed
+ */
+export enum DutyType {
+  BLOCK_PROPOSAL = 'BLOCK_PROPOSAL',
+  CHECKPOINT_PROPOSAL = 'CHECKPOINT_PROPOSAL',
+  ATTESTATION = 'ATTESTATION',
+  ATTESTATIONS_AND_SIGNERS = 'ATTESTATIONS_AND_SIGNERS',
+  GOVERNANCE_VOTE = 'GOVERNANCE_VOTE',
+  SLASHING_VOTE = 'SLASHING_VOTE',
+  AUTH_REQUEST = 'AUTH_REQUEST',
+  TXS = 'TXS',
+}
+
+/**
+ * Signing context for block proposals.
+ * Includes both the block number and the checkpoint number the block belongs to.
+ */
+export interface BlockProposalSigningContext {
+  slot: SlotNumber;
+  blockNumber: BlockNumber;
+  checkpointNumber: CheckpointNumber;
+  /** Block index within checkpoint (0, 1, 2...). Required for block proposals. */
+  blockIndexWithinCheckpoint: IndexWithinCheckpoint;
+  dutyType: DutyType.BLOCK_PROPOSAL;
+}
+
+/**
+ * Signing context for checkpoint proposals.
+ * Includes the checkpoint number being proposed, but not a block number.
+ */
+export interface CheckpointProposalSigningContext {
+  slot: SlotNumber;
+  checkpointNumber: CheckpointNumber;
+  dutyType: DutyType.CHECKPOINT_PROPOSAL;
+}
+
+/**
+ * Signing context for attestation duties (checkpoint attestations).
+ * Includes the checkpoint number when available (from proposal validation).
+ */
+export interface AttestationSigningContext {
+  slot: SlotNumber;
+  checkpointNumber: CheckpointNumber;
+  dutyType: DutyType.ATTESTATION | DutyType.ATTESTATIONS_AND_SIGNERS;
+}
+
+/**
+ * Signing context for governance/slashing votes which only need slot for HA protection.
+ */
+export interface VoteSigningContext {
+  slot: SlotNumber;
+  dutyType: DutyType.GOVERNANCE_VOTE | DutyType.SLASHING_VOTE;
+}
+
+/**
+ * Signing context for duties which don't require slot/blockNumber
+ * as they don't need HA protection (AUTH_REQUEST, TXS).
+ */
+export interface NoHAProtectionSigningContext {
+  dutyType: DutyType.AUTH_REQUEST | DutyType.TXS;
+}
+
+/**
+ * Signing contexts that require HA protection (excludes AUTH_REQUEST and TXS).
+ * Used by the HA signer's signWithProtection method.
+ */
+export type HAProtectedSigningContext =
+  | BlockProposalSigningContext
+  | CheckpointProposalSigningContext
+  | AttestationSigningContext
+  | VoteSigningContext;
+
+/**
+ * Context required for slashing protection during signing operations.
+ * Uses discriminated union to enforce type safety:
+ * - BLOCK_PROPOSAL duties have blockNumber, checkpointNumber, and blockIndexWithinCheckpoint
+ * - CHECKPOINT_PROPOSAL duties have checkpointNumber
+ * - ATTESTATION/ATTESTATIONS_AND_SIGNERS duties have only slot
+ * - Vote duties have only slot
+ * - AUTH_REQUEST and TXS duties don't need HA protection
+ */
+export type SigningContext = HAProtectedSigningContext | NoHAProtectionSigningContext;
+
+/**
+ * Type guard to check if a SigningContext requires HA protection.
+ * Returns true for contexts that need HA protection, false for AUTH_REQUEST and TXS.
+ */
+export function isHAProtectedContext(context: SigningContext): context is HAProtectedSigningContext {
+  return context.dutyType !== DutyType.AUTH_REQUEST && context.dutyType !== DutyType.TXS;
+}
+
+/**
+ * Gets the block number from a signing context.
+ * Only BLOCK_PROPOSAL duties carry a block number; all others return BlockNumber(0).
+ */
+export function getBlockNumberFromSigningContext(context: HAProtectedSigningContext): BlockNumber {
+  if (context.dutyType === DutyType.BLOCK_PROPOSAL) {
+    return context.blockNumber;
+  }
+  return BlockNumber(0);
+}
+
+/**
+ * Gets the checkpoint number from a signing context.
+ * BLOCK_PROPOSAL, CHECKPOINT_PROPOSAL, ATTESTATION, and ATTESTATIONS_AND_SIGNERS duties carry a checkpoint number;
+ * vote duties return CheckpointNumber(0).
+ */
+export function getCheckpointNumberFromSigningContext(context: HAProtectedSigningContext): CheckpointNumber {
+  if (
+    context.dutyType === DutyType.BLOCK_PROPOSAL ||
+    context.dutyType === DutyType.CHECKPOINT_PROPOSAL ||
+    context.dutyType === DutyType.ATTESTATION ||
+    context.dutyType === DutyType.ATTESTATIONS_AND_SIGNERS
+  ) {
+    return context.checkpointNumber;
+  }
+  return CheckpointNumber(0);
+}

package/src/hash/hash.ts

@@ -1,4 +1,4 @@
-import { GeneratorIndex, NULL_MSG_SENDER_CONTRACT_ADDRESS } from '@aztec/constants';
+import { DomainSeparator, NULL_MSG_SENDER_CONTRACT_ADDRESS } from '@aztec/constants';
 import { poseidon2Hash, poseidon2HashWithSeparator } from '@aztec/foundation/crypto/poseidon';
 import { sha256ToField } from '@aztec/foundation/crypto/sha256';
 import { Fr } from '@aztec/foundation/curves/bn254';
@@ -23,7 +23,7 @@ export async function hashVK(keyAsFields: Fr[]): Promise<Fr> {
  * @returns A note hash nonce.
  */
 export function computeNoteHashNonce(nullifierZero: Fr, noteHashIndex: number): Promise<Fr> {
-  return poseidon2HashWithSeparator([nullifierZero, noteHashIndex], GeneratorIndex.NOTE_HASH_NONCE);
+  return poseidon2HashWithSeparator([nullifierZero, noteHashIndex], DomainSeparator.NOTE_HASH_NONCE);
 }
 
 /**
@@ -34,7 +34,7 @@ export function computeNoteHashNonce(nullifierZero: Fr, noteHashIndex: number):
  * @returns A siloed note hash.
  */
 export function siloNoteHash(contract: AztecAddress, noteHash: Fr): Promise<Fr> {
-  return poseidon2HashWithSeparator([contract, noteHash], GeneratorIndex.SILOED_NOTE_HASH);
+  return poseidon2HashWithSeparator([contract, noteHash], DomainSeparator.SILOED_NOTE_HASH);
 }
 
 /**
@@ -44,7 +44,7 @@ export function siloNoteHash(contract: AztecAddress, noteHash: Fr): Promise<Fr>
  * @returns A unique note hash.
  */
 export function computeUniqueNoteHash(noteNonce: Fr, siloedNoteHash: Fr): Promise<Fr> {
-  return poseidon2HashWithSeparator([noteNonce, siloedNoteHash], GeneratorIndex.UNIQUE_NOTE_HASH);
+  return poseidon2HashWithSeparator([noteNonce, siloedNoteHash], DomainSeparator.UNIQUE_NOTE_HASH);
 }
 
 /**
@@ -55,7 +55,36 @@ export function computeUniqueNoteHash(noteNonce: Fr, siloedNoteHash: Fr): Promis
  * @returns A siloed nullifier.
  */
 export function siloNullifier(contract: AztecAddress, innerNullifier: Fr): Promise<Fr> {
-  return poseidon2HashWithSeparator([contract, innerNullifier], GeneratorIndex.SILOED_NULLIFIER);
+  return poseidon2HashWithSeparator([contract, innerNullifier], DomainSeparator.SILOED_NULLIFIER);
+}
+
+/**
+ * Computes the siloed private initialization nullifier for a contract, given its address and initialization hash.
+ * @param contract - The contract address.
+ * @param initializationHash - The contract's initialization hash.
+ * @returns The siloed private initialization nullifier.
+ */
+export async function computeSiloedPrivateInitializationNullifier(
+  contract: AztecAddress,
+  initializationHash: Fr,
+): Promise<Fr> {
+  const innerNullifier = await poseidon2HashWithSeparator(
+    [contract, initializationHash],
+    DomainSeparator.PRIVATE_INITIALIZATION_NULLIFIER,
+  );
+  return siloNullifier(contract, innerNullifier);
+}
+
+/**
+ * Computes the siloed public initialization nullifier for a contract. Not all contracts emit this nullifier: it is only
+ * emitted when the contract has public functions that perform initialization checks (i.e. external public functions that
+ * are not `#[noinitcheck]` or `#[only_self]`).
+ * @param contract - The contract address.
+ * @returns The siloed public initialization nullifier.
+ */
+export async function computeSiloedPublicInitializationNullifier(contract: AztecAddress): Promise<Fr> {
+  const innerNullifier = await poseidon2HashWithSeparator([contract], DomainSeparator.PUBLIC_INITIALIZATION_NULLIFIER);
+  return siloNullifier(contract, innerNullifier);
 }
 
 /**
@@ -69,6 +98,15 @@ export function computeProtocolNullifier(txRequestHash: Fr): Promise<Fr> {
   return siloNullifier(AztecAddress.fromBigInt(NULL_MSG_SENDER_CONTRACT_ADDRESS), txRequestHash);
 }
 
+/** Domain-separates a raw log tag with the given domain separator. */
+export function computeLogTag(rawTag: number | bigint | boolean | Fr | Buffer, domSep: DomainSeparator): Promise<Fr> {
+  return poseidon2HashWithSeparator([new Fr(rawTag)], domSep);
+}
+
+export function computeSiloedPrivateLogFirstField(contract: AztecAddress, field: Fr): Promise<Fr> {
+  return poseidon2HashWithSeparator([contract, field], DomainSeparator.PRIVATE_LOG_FIRST_FIELD);
+}
+
 /**
  * Computes a public data tree value ready for insertion.
  * @param value - Raw public data tree value to hash into a tree-insertion-ready value.
@@ -87,7 +125,7 @@ export function computePublicDataTreeValue(value: Fr): Fr {
 
  */
 export function computePublicDataTreeLeafSlot(contractAddress: AztecAddress, storageSlot: Fr): Promise<Fr> {
-  return poseidon2HashWithSeparator([contractAddress, storageSlot], GeneratorIndex.PUBLIC_LEAF_SLOT);
+  return poseidon2HashWithSeparator([contractAddress, storageSlot], DomainSeparator.PUBLIC_LEAF_SLOT);
 }
 
 /**
@@ -101,7 +139,7 @@ export function computeVarArgsHash(args: Fr[]): Promise<Fr> {
     return Promise.resolve(Fr.ZERO);
   }
 
-  return poseidon2HashWithSeparator(args, GeneratorIndex.FUNCTION_ARGS);
+  return poseidon2HashWithSeparator(args, DomainSeparator.FUNCTION_ARGS);
 }
 
 /**
@@ -110,7 +148,7 @@ export function computeVarArgsHash(args: Fr[]): Promise<Fr> {
  * @returns Hash of the calldata.
  */
 export function computeCalldataHash(calldata: Fr[]): Promise<Fr> {
-  return poseidon2HashWithSeparator(calldata, GeneratorIndex.PUBLIC_CALLDATA);
+  return poseidon2HashWithSeparator(calldata, DomainSeparator.PUBLIC_CALLDATA);
 }
 
 /**
@@ -120,13 +158,13 @@ export function computeCalldataHash(calldata: Fr[]): Promise<Fr> {
  * @returns The hash
  */
 export function computeSecretHash(secret: Fr): Promise<Fr> {
-  return poseidon2HashWithSeparator([secret], GeneratorIndex.SECRET_HASH);
+  return poseidon2HashWithSeparator([secret], DomainSeparator.SECRET_HASH);
 }
 
 export async function computeL1ToL2MessageNullifier(contract: AztecAddress, messageHash: Fr, secret: Fr) {
   const innerMessageNullifier = await poseidon2HashWithSeparator(
     [messageHash, secret],
-    GeneratorIndex.MESSAGE_NULLIFIER,
+    DomainSeparator.MESSAGE_NULLIFIER,
   );
   return siloNullifier(contract, innerMessageNullifier);
 }

package/src/hash/map_slot.ts

@@ -1,4 +1,4 @@
-import { GeneratorIndex } from '@aztec/constants';
+import { DomainSeparator } from '@aztec/constants';
 import { poseidon2HashWithSeparator } from '@aztec/foundation/crypto/poseidon';
 import type { Fr } from '@aztec/foundation/curves/bn254';
 
@@ -15,5 +15,5 @@ export function deriveStorageSlotInMap(
     toField: () => Fr;
   },
 ): Promise<Fr> {
-  return poseidon2HashWithSeparator([mapSlot, key.toField()], GeneratorIndex.PUBLIC_STORAGE_MAP_SLOT);
+  return poseidon2HashWithSeparator([mapSlot, key.toField()], DomainSeparator.PUBLIC_STORAGE_MAP_SLOT);
 }

package/src/interfaces/allowed_element.ts

@@ -6,18 +6,38 @@ import type { FunctionSelector } from '../abi/function_selector.js';
 import type { AztecAddress } from '../aztec-address/index.js';
 import { schemas, zodFor } from '../schemas/index.js';
 
-type AllowedInstance = { address: AztecAddress };
-type AllowedInstanceFunction = { address: AztecAddress; selector: FunctionSelector };
-type AllowedClass = { classId: Fr };
-type AllowedClassFunction = { classId: Fr; selector: FunctionSelector };
+type AllowedInstanceFunction = {
+  address: AztecAddress;
+  selector: FunctionSelector;
+  onlySelf?: boolean;
+  rejectNullMsgSender?: boolean;
+  calldataLength?: number;
+};
+type AllowedClassFunction = {
+  classId: Fr;
+  selector: FunctionSelector;
+  onlySelf?: boolean;
+  rejectNullMsgSender?: boolean;
+  calldataLength?: number;
+};
 
-export type AllowedElement = AllowedInstance | AllowedInstanceFunction | AllowedClass | AllowedClassFunction;
+export type AllowedElement = AllowedInstanceFunction | AllowedClassFunction;
 
 export const AllowedElementSchema = zodFor<AllowedElement>()(
   z.union([
-    z.object({ address: schemas.AztecAddress, selector: schemas.FunctionSelector }),
-    z.object({ address: schemas.AztecAddress }),
-    z.object({ classId: schemas.Fr, selector: schemas.FunctionSelector }),
-    z.object({ classId: schemas.Fr }),
+    z.object({
+      address: schemas.AztecAddress,
+      selector: schemas.FunctionSelector,
+      onlySelf: z.boolean().optional(),
+      rejectNullMsgSender: z.boolean().optional(),
+      calldataLength: z.number().optional(),
+    }),
+    z.object({
+      classId: schemas.Fr,
+      selector: schemas.FunctionSelector,
+      onlySelf: z.boolean().optional(),
+      rejectNullMsgSender: z.boolean().optional(),
+      calldataLength: z.number().optional(),
+    }),
   ]),
 );

package/src/interfaces/archiver.ts

@@ -4,12 +4,14 @@ import type { ApiSchemaFor } from '@aztec/foundation/schemas';
 
 import { z } from 'zod';
 
+import { BlockDataSchema } from '../block/block_data.js';
 import { BlockHash } from '../block/block_hash.js';
 import { CheckpointedL2Block } from '../block/checkpointed_l2_block.js';
 import { L2Block } from '../block/l2_block.js';
 import { type L2BlockSource, L2TipsSchema } from '../block/l2_block_source.js';
 import { ValidateCheckpointResultSchema } from '../block/validate_block_result.js';
 import { Checkpoint } from '../checkpoint/checkpoint.js';
+import { CheckpointDataSchema, ProposedCheckpointDataSchema } from '../checkpoint/checkpoint_data.js';
 import { PublishedCheckpoint } from '../checkpoint/published_checkpoint.js';
 import {
   ContractClassPublicSchema,
@@ -84,6 +86,7 @@ export const ArchiverApiSchema: ApiSchemaFor<ArchiverApi> = {
   getBlockNumber: z.function().args().returns(BlockNumberSchema),
   getProvenBlockNumber: z.function().args().returns(BlockNumberSchema),
   getCheckpointedL2BlockNumber: z.function().args().returns(BlockNumberSchema),
+  getCheckpointNumber: z.function().args().returns(CheckpointNumberSchema),
   getFinalizedL2BlockNumber: z.function().args().returns(BlockNumberSchema),
   getBlock: z.function().args(BlockNumberSchema).returns(L2Block.schema.optional()),
   getBlockHeader: z
@@ -104,14 +107,17 @@ export const ArchiverApiSchema: ApiSchemaFor<ArchiverApi> = {
   getCheckpointedBlockByArchive: z.function().args(schemas.Fr).returns(CheckpointedL2Block.schema.optional()),
   getBlockHeaderByHash: z.function().args(BlockHash.schema).returns(BlockHeader.schema.optional()),
   getBlockHeaderByArchive: z.function().args(schemas.Fr).returns(BlockHeader.schema.optional()),
+  getBlockData: z.function().args(BlockNumberSchema).returns(BlockDataSchema.optional()),
+  getBlockDataByArchive: z.function().args(schemas.Fr).returns(BlockDataSchema.optional()),
   getL2Block: z.function().args(BlockNumberSchema).returns(L2Block.schema.optional()),
   getL2BlockByHash: z.function().args(BlockHash.schema).returns(L2Block.schema.optional()),
   getL2BlockByArchive: z.function().args(schemas.Fr).returns(L2Block.schema.optional()),
   getTxEffect: z.function().args(TxHash.schema).returns(indexedTxSchema().optional()),
   getSettledTxReceipt: z.function().args(TxHash.schema).returns(TxReceipt.schema.optional()),
-  getL2SlotNumber: z.function().args().returns(schemas.SlotNumber.optional()),
-  getL2EpochNumber: z.function().args().returns(EpochNumberSchema.optional()),
+  getSyncedL2SlotNumber: z.function().args().returns(schemas.SlotNumber.optional()),
+  getSyncedL2EpochNumber: z.function().args().returns(EpochNumberSchema.optional()),
   getCheckpointsForEpoch: z.function().args(EpochNumberSchema).returns(z.array(Checkpoint.schema)),
+  getCheckpointsDataForEpoch: z.function().args(EpochNumberSchema).returns(z.array(CheckpointDataSchema)),
   getCheckpointedBlocksForEpoch: z.function().args(EpochNumberSchema).returns(z.array(CheckpointedL2Block.schema)),
   getBlocksForSlot: z.function().args(schemas.SlotNumber).returns(z.array(L2Block.schema)),
   getCheckpointedBlockHeadersForEpoch: z.function().args(EpochNumberSchema).returns(z.array(BlockHeader.schema)),
@@ -144,6 +150,8 @@ export const ArchiverApiSchema: ApiSchemaFor<ArchiverApi> = {
     .args()
     .returns(z.object({ genesisArchiveRoot: schemas.Fr })),
   getL1Timestamp: z.function().args().returns(schemas.BigInt.optional()),
+  getProposedCheckpoint: z.function().args().returns(ProposedCheckpointDataSchema.optional()),
+  getProposedCheckpointOnly: z.function().args().returns(ProposedCheckpointDataSchema.optional()),
   syncImmediate: z.function().args().returns(z.void()),
   isPendingChainInvalid: z.function().args().returns(z.boolean()),
   getPendingChainValidationStatus: z.function().args().returns(ValidateCheckpointResultSchema),

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

@@ -3,7 +3,8 @@ import { createSafeJsonRpcClient, defaultFetch } from '@aztec/foundation/json-rp
 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 +37,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,11 +47,28 @@ 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[]>;
-
   /** Returns all offenses applicable for the given round. */
   getSlashOffenses(round: bigint | 'all' | 'current'): Promise<Offense[]>;
+
+  /**
+   * Reloads keystore configuration from disk.
+   *
+   * What is updated:
+   * - Validator attester keys
+   * - Coinbase address per validator
+   * - Fee recipient address per validator
+   *
+   * What is NOT updated (requires node restart):
+   * - L1 publisher signers (the funded accounts that send L1 transactions)
+   * - Prover keys
+   * - HA signer PostgreSQL connections
+   *
+   * Notes:
+   * - New validators must use a publisher key that was already configured at node
+   *   startup (or omit the publisher field to fall back to the attester key).
+   *   A validator with an unknown publisher key will cause the reload to be rejected.
+   */
+  reloadKeystore(): Promise<void>;
 }
 
 // L1 contracts are not mutable via admin updates.
@@ -80,24 +99,26 @@ 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()),
+  rollbackTo: z.function().args(z.number(), optional(z.boolean()), optional(z.boolean())).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()),
 };
 
 export function createAztecNodeAdminClient(
   url: string,
   versions: Partial<ComponentsVersions> = {},
   fetch = defaultFetch,
+  apiKey?: string,
 ): AztecNodeAdmin {
   return createSafeJsonRpcClient<AztecNodeAdmin>(url, AztecNodeAdminApiSchema, {
     namespaceMethods: 'nodeAdmin',
     fetch,
     onResponse: getVersioningResponseHandler(versions),
+    ...(apiKey ? { extraHeaders: { 'x-api-key': apiKey } } : {}),
   });
 }

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

@@ -0,0 +1,40 @@
+import { createSafeJsonRpcClient, defaultFetch } from '@aztec/foundation/json-rpc/client';
+
+import { z } from 'zod';
+
+import type { ApiSchemaFor } 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>;
+}
+
+export const AztecNodeDebugApiSchema: ApiSchemaFor<AztecNodeDebug> = {
+  mineBlock: z.function().returns(z.void()),
+};
+
+export function createAztecNodeDebugClient(
+  url: string,
+  versions: Partial<ComponentsVersions> = {},
+  fetch = defaultFetch,
+  apiKey?: string,
+): AztecNodeDebug {
+  return createSafeJsonRpcClient<AztecNodeDebug>(url, AztecNodeDebugApiSchema, {
+    namespaceMethods: 'nodeDebug',
+    fetch,
+    onResponse: getVersioningResponseHandler(versions),
+    ...(apiKey ? { extraHeaders: { 'x-api-key': apiKey } } : {}),
+  });
+}

package/src/interfaces/aztec-node.ts

@@ -4,7 +4,9 @@ import {
   BlockNumber,
   BlockNumberPositiveSchema,
   BlockNumberSchema,
+  CheckpointNumber,
   CheckpointNumberPositiveSchema,
+  CheckpointNumberSchema,
   EpochNumber,
   EpochNumberSchema,
   type SlotNumber,
@@ -23,6 +25,7 @@ import { CheckpointedL2Block } from '../block/checkpointed_l2_block.js';
 import { type DataInBlock, dataInBlockSchemaFor } from '../block/in_block.js';
 import { L2Block } from '../block/l2_block.js';
 import { type L2BlockSource, type L2Tips, L2TipsSchema } from '../block/l2_block_source.js';
+import { CheckpointDataSchema } from '../checkpoint/checkpoint_data.js';
 import { PublishedCheckpoint } from '../checkpoint/published_checkpoint.js';
 import {
   type ContractClassPublic,
@@ -34,6 +37,7 @@ import {
   type ProtocolContractAddresses,
   ProtocolContractAddressesSchema,
 } from '../contract/index.js';
+import { ManaUsageEstimate } from '../gas/fee_math.js';
 import { GasFees } from '../gas/gas_fees.js';
 import { SiloedTag, Tag, TxScopedL2Log } from '../logs/index.js';
 import { type LogFilter, LogFilterSchema } from '../logs/log_filter.js';
@@ -72,7 +76,12 @@ import { type WorldStateSyncStatus, WorldStateSyncStatusSchema } from './world_s
 export interface AztecNode
   extends Pick<
     L2BlockSource,
-    'getBlocks' | 'getCheckpoints' | 'getBlockHeader' | 'getL2Tips' | 'getCheckpointedBlocks'
+    | 'getBlocks'
+    | 'getCheckpoints'
+    | 'getBlockHeader'
+    | 'getL2Tips'
+    | 'getCheckpointedBlocks'
+    | 'getCheckpointsDataForEpoch'
   > {
   /**
    * Returns the tips of the L2 chain.
@@ -114,6 +123,7 @@ export interface AztecNode
    * @param referenceBlock - The block parameter (block number, block hash, or 'latest') at which to get the data.
    * @param nullifier - Nullifier we try to find the low nullifier witness for.
    * @returns The low nullifier membership witness (if found).
+   * @throws If the nullifier already exists in the tree, since non-inclusion cannot be proven.
    * @remarks Low nullifier witness can be used to perform a nullifier non-inclusion proof by leveraging the "linked
    * list structure" of leaves and proving that a lower nullifier is pointing to a bigger next value than the nullifier
    * we are trying to prove non-inclusion for.
@@ -172,14 +182,14 @@ export interface AztecNode
     l1ToL2Message: Fr,
   ): Promise<[bigint, SiblingPath<typeof L1_TO_L2_MSG_TREE_HEIGHT>] | undefined>;
 
-  /** Returns the L2 block number in which this L1 to L2 message becomes available, or undefined if not found. */
-  getL1ToL2MessageBlock(l1ToL2Message: Fr): Promise<BlockNumber | undefined>;
+  /** Returns the L2 checkpoint number in which this L1 to L2 message becomes available, or undefined if not found. */
+  getL1ToL2MessageCheckpoint(l1ToL2Message: Fr): Promise<CheckpointNumber | undefined>;
 
   /**
    * Returns whether an L1 to L2 message is synced by archiver.
    * @param l1ToL2Message - The L1 to L2 message to check.
    * @returns Whether the message is synced.
-   * @deprecated Use `getL1ToL2MessageBlock` instead. This method may return true even if the message is not ready to use.
+   * @deprecated Use `getL1ToL2MessageCheckpoint` instead. This method may return true even if the message is not ready to use.
    */
   isL1ToL2MessageSynced(l1ToL2Message: Fr): Promise<boolean>;
 
@@ -230,6 +240,12 @@ export interface AztecNode
    */
   getCheckpointedBlockNumber(): Promise<BlockNumber>;
 
+  /**
+   * Method to fetch the latest checkpoint number synchronized by the node.
+   * @returns The checkpoint number.
+   */
+  getCheckpointNumber(): Promise<CheckpointNumber>;
+
   /**
    * Method to determine if the node is ready to accept transactions.
    * @returns - Flag indicating the readiness for tx submission.
@@ -257,6 +273,15 @@ export interface AztecNode
    */
   getCurrentMinFees(): Promise<GasFees>;
 
+  /**
+   * Returns predicted min fees for the current slot and next N slots.
+   * Each entry accounts for the L1 gas oracle transition and congestion growth based on the
+   * given mana usage estimate. Defaults to target usage (steady state).
+   * @param manaUsage - Expected mana usage per checkpoint (none, target, or limit).
+   * @returns An array of GasFees, one per slot in the prediction window.
+   */
+  getPredictedMinFees(manaUsage?: ManaUsageEstimate): Promise<GasFees[]>;
+
   /**
    * Method to fetch the current max priority fee of txs in the mempool.
    * @returns The current max priority fees.
@@ -443,7 +468,7 @@ export interface AztecNode
   /**
    * Returns true if the transaction is valid for inclusion at the current state. Valid transactions can be
    * made invalid by *other* transactions if e.g. they emit the same nullifiers, or come become invalid
-   * due to e.g. the include_by_timestamp property.
+   * due to e.g. the expiration_timestamp property.
    * @param tx - The transaction to validate for correctness.
    * @param isSimulation - True if the transaction is a simulated one without generated proofs. (Optional)
    * @param skipFeeEnforcement - True if the validation of the fee should be skipped. Useful when the simulation is for estimating fee (Optional)
@@ -517,7 +542,7 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
     .args(BlockParameterSchema, schemas.Fr)
     .returns(z.tuple([schemas.BigInt, SiblingPath.schemaFor(L1_TO_L2_MSG_TREE_HEIGHT)]).optional()),
 
-  getL1ToL2MessageBlock: z.function().args(schemas.Fr).returns(BlockNumberSchema.optional()),
+  getL1ToL2MessageCheckpoint: z.function().args(schemas.Fr).returns(CheckpointNumberSchema.optional()),
 
   isL1ToL2MessageSynced: z.function().args(schemas.Fr).returns(z.boolean()),
 
@@ -534,6 +559,8 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
 
   getBlockNumber: z.function().returns(BlockNumberSchema),
 
+  getCheckpointNumber: z.function().returns(CheckpointNumberSchema),
+
   getProvenBlockNumber: z.function().returns(BlockNumberSchema),
 
   getCheckpointedBlockNumber: z.function().returns(BlockNumberSchema),
@@ -557,8 +584,15 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
     .args(BlockNumberPositiveSchema, z.number().gt(0).lte(MAX_RPC_BLOCKS_LEN))
     .returns(z.array(CheckpointedL2Block.schema)),
 
+  getCheckpointsDataForEpoch: z.function().args(EpochNumberSchema).returns(z.array(CheckpointDataSchema)),
+
   getCurrentMinFees: z.function().returns(GasFees.schema),
 
+  getPredictedMinFees: z
+    .function()
+    .args(optional(z.nativeEnum(ManaUsageEstimate)))
+    .returns(z.array(GasFees.schema)),
+
   getMaxPriorityFees: z.function().returns(GasFees.schema),
 
   getNodeVersion: z.function().returns(z.string()),