@aztec-labs/stdlib 6.0.0-nightly.20260829

package/src/interfaces/archiver.ts

@@ -0,0 +1,175 @@
+import { BlockNumberSchema, CheckpointNumberSchema, EpochNumberSchema } from '@aztec-labs/foundation/branded-types';
+import type { ApiSchemaFor } from '@aztec-labs/foundation/schemas';
+import { z } from 'zod';
+
+import { BlockDataSchema } from '../block/block_data.js';
+import { L2Block } from '../block/l2_block.js';
+import {
+  BlockQuerySchema,
+  BlocksQuerySchema,
+  CheckpointQuerySchema,
+  CheckpointsQuerySchema,
+  type L2BlockSource,
+  L2TipsSchema,
+  ProposedCheckpointQuerySchema,
+} from '../block/l2_block_source.js';
+import { ValidateCheckpointResultSchema } from '../block/validate_block_result.js';
+import { CheckpointDataSchema, ProposedCheckpointDataSchema } from '../checkpoint/checkpoint_data.js';
+import { PublishedCheckpoint } from '../checkpoint/published_checkpoint.js';
+import {
+  ContractClassPublicSchema,
+  type ContractDataSource,
+  ContractInstanceWithAddressSchema,
+} from '../contract/index.js';
+import { L1RollupConstantsSchema } from '../epoch-helpers/index.js';
+import { LogResultSchema } from '../logs/log_result.js';
+import { PrivateLogsQuerySchema, PublicLogsQuerySchema } from '../logs/logs_query.js';
+import { InboxBucketSchema } from '../messaging/inbox_bucket.js';
+import type { L1ToL2MessageSource } from '../messaging/l1_to_l2_message_source.js';
+import { L2ToL1MembershipWitnessSchema } from '../messaging/l2_to_l1_membership.js';
+import { optional, schemas } from '../schemas/schemas.js';
+import { indexedTxSchema } from '../tx/indexed_tx_effect.js';
+import { TxHash } from '../tx/tx_hash.js';
+import type { L2LogsSource } from './l2_logs_source.js';
+
+/**
+ * The archiver configuration.
+ */
+export type ArchiverSpecificConfig = {
+  /** The polling interval in ms for retrieving new L2 blocks and encrypted logs. */
+  archiverPollingIntervalMS?: number;
+
+  /** The number of L2 blocks the archiver will attempt to download at a time. */
+  archiverBatchSize?: number;
+
+  /** The polling interval viem uses in ms */
+  viemPollingIntervalMS?: number;
+
+  /** The maximum possible size of the archiver DB in KB. Overwrites the general dataStoreMapSizeKb. */
+  archiverStoreMapSizeKb?: number;
+
+  /** Maximum allowed drift in seconds between the Ethereum client and current time. */
+  maxAllowedEthClientDriftSeconds?: number;
+
+  /** Whether to allow starting the archiver without debug/trace method support on Ethereum hosts */
+  ethereumAllowNoDebugHosts?: boolean;
+
+  /** Skip the startup check that probes the L1 RPC for historical logs on the Rollup contract. */
+  archiverSkipHistoricalLogsCheck?: boolean;
+
+  /** Skip validating checkpoint attestations (for testing purposes only) */
+  skipValidateCheckpointAttestations?: boolean;
+
+  /** Skip promoting proposed checkpoints during L1 sync (for testing purposes only) */
+  skipPromoteProposedCheckpointDuringL1Sync?: boolean;
+
+  /** Local tolerance in seconds before pruning an orphan block when no checkpoint proposal was received. */
+  orphanPruneNoProposalTolerance?: number;
+
+  /** Skip pruning orphan proposed blocks that have no matching proposed checkpoint. */
+  skipOrphanProposedBlockPruning?: boolean;
+
+  /**
+   * Preload the standard contracts (AuthRegistry, PublicChecks, HandshakeRegistry) into the contract store at block 0.
+   * For test environments only: it must only be set when genesis also seeds the matching registration/deployment
+   * nullifiers, otherwise a later onchain publish of a preloaded class would collide with the block-0 preload.
+   */
+  testPreloadStandardContracts?: boolean;
+};
+
+export const ArchiverSpecificConfigSchema = z.object({
+  archiverPollingIntervalMS: schemas.Integer.optional(),
+  archiverBatchSize: schemas.Integer.optional(),
+  viemPollingIntervalMS: schemas.Integer.optional(),
+  archiverStoreMapSizeKb: schemas.Integer.optional(),
+  maxAllowedEthClientDriftSeconds: schemas.Integer.optional(),
+  ethereumAllowNoDebugHosts: z.boolean().optional(),
+  archiverSkipHistoricalLogsCheck: z.boolean().optional(),
+  skipValidateCheckpointAttestations: z.boolean().optional(),
+  skipPromoteProposedCheckpointDuringL1Sync: z.boolean().optional(),
+  orphanPruneNoProposalTolerance: schemas.Integer.optional(),
+  skipOrphanProposedBlockPruning: z.boolean().optional(),
+  testPreloadStandardContracts: z.boolean().optional(),
+});
+
+export type ArchiverApi = Omit<
+  L2BlockSource & L2LogsSource & ContractDataSource & L1ToL2MessageSource,
+  'start' | 'stop' | 'getGenesisBlockHash'
+>;
+
+export const ArchiverApiSchema: ApiSchemaFor<ArchiverApi> = {
+  getRollupAddress: z.function({ input: z.tuple([]), output: schemas.EthAddress }),
+  getRegistryAddress: z.function({ input: z.tuple([]), output: schemas.EthAddress }),
+  getBlockNumber: z.function({ input: z.tuple([optional(BlockQuerySchema)]), output: BlockNumberSchema.optional() }),
+  getCheckpointNumber: z.function({ input: z.tuple([]), output: CheckpointNumberSchema }),
+  getCheckpoint: z.function({ input: z.tuple([CheckpointQuerySchema]), output: PublishedCheckpoint.schema.optional() }),
+  getCheckpoints: z.function({ input: z.tuple([CheckpointsQuerySchema]), output: z.array(PublishedCheckpoint.schema) }),
+  getCheckpointData: z.function({ input: z.tuple([CheckpointQuerySchema]), output: CheckpointDataSchema.optional() }),
+  getCheckpointsData: z.function({ input: z.tuple([CheckpointsQuerySchema]), output: z.array(CheckpointDataSchema) }),
+  getTxEffect: z.function({ input: z.tuple([TxHash.schema]), output: indexedTxSchema().optional() }),
+  // Reads Outbox roots lazily, pinned to the node's synced L1 block. Caveat: cached roots that are
+  // sealed and L1-finalized are not re-validated, so a reorg deeper than L1 finality could leave the
+  // node serving a witness against a no-longer-canonical root.
+  getL2ToL1MembershipWitness: z.function({
+    input: z.tuple([TxHash.schema, schemas.Fr, optional(schemas.Integer)]),
+    output: L2ToL1MembershipWitnessSchema.optional(),
+  }),
+  getSyncedL2SlotNumber: z.function({ input: z.tuple([]), output: schemas.SlotNumber.optional() }),
+  getSyncedL2EpochNumber: z.function({ input: z.tuple([]), output: EpochNumberSchema.optional() }),
+  getBlocksForSlot: z.function({ input: z.tuple([schemas.SlotNumber]), output: z.array(L2Block.schema) }),
+  isEpochComplete: z.function({ input: z.tuple([EpochNumberSchema]), output: z.boolean() }),
+  getL2Tips: z.function({ input: z.tuple([]), output: L2TipsSchema }),
+  getPrivateLogsByTags: z.function({
+    input: z.tuple([PrivateLogsQuerySchema]),
+    output: z.array(z.array(LogResultSchema)),
+  }),
+  getPublicLogsByTags: z.function({
+    input: z.tuple([PublicLogsQuerySchema]),
+    output: z.array(z.array(LogResultSchema)),
+  }),
+  getContractClass: z.function({ input: z.tuple([schemas.Fr]), output: ContractClassPublicSchema.optional() }),
+  getBytecodeCommitment: z.function({ input: z.tuple([schemas.Fr]), output: schemas.Fr }),
+  getContract: z.function({
+    input: z.tuple([schemas.AztecAddress, schemas.BigInt]),
+    output: ContractInstanceWithAddressSchema.optional(),
+  }),
+  getContractClassIds: z.function({ input: z.tuple([]), output: z.array(schemas.Fr) }),
+  registerContractFunctionSignatures: z.function({ input: z.tuple([z.array(z.string())]), output: z.void() }),
+  getL1ToL2MessageIndex: z.function({ input: z.tuple([schemas.Fr]), output: schemas.BigInt.optional() }),
+  getLatestInboxBucketAtOrBefore: z.function({
+    input: z.tuple([schemas.BigInt]),
+    output: InboxBucketSchema.optional(),
+  }),
+  getInboxBucket: z.function({ input: z.tuple([schemas.BigInt]), output: InboxBucketSchema.optional() }),
+  getInboxBucketByTotalMsgCount: z.function({
+    input: z.tuple([schemas.BigInt]),
+    output: InboxBucketSchema.optional(),
+  }),
+  getL1ToL2MessagesBetweenBuckets: z.function({
+    input: z.tuple([schemas.BigInt, schemas.BigInt]),
+    output: z.array(schemas.Fr),
+  }),
+  getL1ToL2MessagesBetweenLeafCounts: z.function({
+    input: z.tuple([schemas.BigInt, schemas.BigInt]),
+    output: z.array(schemas.Fr),
+  }),
+  getDebugFunctionName: z.function({
+    input: z.tuple([schemas.AztecAddress, schemas.FunctionSelector]),
+    output: optional(z.string()),
+  }),
+  getL1Constants: z.function({ input: z.tuple([]), output: L1RollupConstantsSchema }),
+  isPruneDueAtSlot: z.function({ input: z.tuple([schemas.SlotNumber]), output: z.boolean() }),
+  getGenesisValues: z.function({ input: z.tuple([]), output: z.object({ genesisArchiveRoot: schemas.Fr }) }),
+  getL1Timestamp: z.function({ input: z.tuple([]), output: schemas.BigInt.optional() }),
+  getProposedCheckpointData: z.function({
+    input: z.tuple([optional(ProposedCheckpointQuerySchema)]),
+    output: ProposedCheckpointDataSchema.optional(),
+  }),
+  syncImmediate: z.function({ input: z.tuple([]), output: z.void() }),
+  isPendingChainInvalid: z.function({ input: z.tuple([]), output: z.boolean() }),
+  getPendingChainValidationStatus: z.function({ input: z.tuple([]), output: ValidateCheckpointResultSchema }),
+  getBlock: z.function({ input: z.tuple([BlockQuerySchema]), output: L2Block.schema.optional() }),
+  getBlocks: z.function({ input: z.tuple([BlocksQuerySchema]), output: z.array(L2Block.schema) }),
+  getBlockData: z.function({ input: z.tuple([BlockQuerySchema]), output: BlockDataSchema.optional() }),
+  getBlocksData: z.function({ input: z.tuple([BlocksQuerySchema]), output: z.array(BlockDataSchema) }),
+};

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

@@ -0,0 +1,140 @@
+import type { L1ContractAddresses } from '@aztec-labs/ethereum/l1-contract-addresses';
+import { createSafeJsonRpcClient, defaultFetch } from '@aztec-labs/foundation/json-rpc/client';
+import { z } from 'zod';
+
+import type { ApiSchemaFor } from '../schemas/schemas.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';
+import { type ProverConfig, ProverConfigSchema } from './prover-client.js';
+import { type SlasherConfig, SlasherConfigSchema } from './slasher.js';
+import { type ValidatorClientFullConfig, ValidatorClientFullConfigSchema } from './validator.js';
+
+/**
+ * Aztec node admin API.
+ */
+export interface AztecNodeAdmin {
+  /**
+   * Retrieves the configuration of this node.
+   */
+  getConfig(): Promise<AztecNodeAdminConfig>;
+
+  /**
+   * Updates the configuration of this node.
+   * @param config - Updated configuration to be merged with the current one.
+   */
+  setConfig(config: Partial<AztecNodeAdminConfig>): Promise<void>;
+
+  /**
+   * Pauses syncing, creates a backup of archiver and world-state databases, and uploads them. Returns immediately.
+   * @param location - The location to upload the snapshot to.
+   */
+  startSnapshotUpload(location: string): Promise<void>;
+
+  /**
+   * 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, resumeSync?: boolean): Promise<void>;
+
+  /** Pauses archiver and world state syncing. */
+  pauseSync(): Promise<void>;
+
+  /** Resumes archiver and world state syncing. */
+  resumeSync(): Promise<void>;
+
+  /**
+   * 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[]>;
+
+  /**
+   * 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 contract addresses are pinned at startup and are not mutable via admin updates.
+export type AztecNodeAdminConfig = Omit<ValidatorClientFullConfig, keyof L1ContractAddresses> &
+  SequencerConfig &
+  ProverConfig &
+  SlasherConfig &
+  Pick<
+    ArchiverSpecificConfig,
+    '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({ rollupAddress: true }))
+  .merge(
+    ArchiverSpecificConfigSchema.pick({
+      archiverPollingIntervalMS: true,
+      archiverBatchSize: true,
+      skipValidateCheckpointAttestations: true,
+    }),
+  )
+  .merge(z.object({ maxPendingTxCount: z.number(), skipIncomingProposals: z.boolean().optional() }));
+
+export const AztecNodeAdminApiSchema: ApiSchemaFor<AztecNodeAdmin> = {
+  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(
+  url: string,
+  versions: Partial<ComponentsVersions> = {},
+  fetch = defaultFetch,
+  apiKey?: string,
+): AztecNodeAdmin {
+  return createSafeJsonRpcClient<AztecNodeAdmin>(url, AztecNodeAdminApiSchema, {
+    namespaceMethods: 'aztecAdmin',
+    fetch,
+    onResponse: getVersioningResponseHandler(versions),
+    ...(apiKey ? { extraHeaders: { 'x-api-key': apiKey } } : {}),
+  });
+}

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

@@ -0,0 +1,91 @@
+import { type CheckpointNumber, CheckpointNumberSchema } from '@aztec-labs/foundation/branded-types';
+import { createSafeJsonRpcClient, defaultFetch } from '@aztec-labs/foundation/json-rpc/client';
+import { z } from 'zod';
+
+import { type ApiSchemaFor, optional } from '../schemas/schemas.js';
+import { type ComponentsVersions, getVersioningResponseHandler } from '../versioning/index.js';
+
+const MAX_SIGNATURES_PER_REGISTER_CALL = 100;
+const MAX_SIGNATURE_LEN = 10000;
+
+/**
+ * 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>;
+
+  /**
+   * Warps L1 time forward to at least `targetTimestamp` and builds an empty L2 checkpoint at the next slot boundary,
+   * advancing the L2 timestamp to at least the target. The warp is serialized with block building, so it never
+   * interleaves with an in-flight build. A no-op when `targetTimestamp` is already at or behind the current L1 time.
+   *
+   * @param targetTimestamp - Target L1 timestamp, in seconds.
+   * @throws If no automine sequencer is running (only the automine sequencer supports time warps).
+   */
+  warpL2TimeAtLeastTo(targetTimestamp: number): Promise<void>;
+
+  /**
+   * Warps L1 time forward by at least `duration` seconds from the current L1 time and builds an empty L2 checkpoint
+   * at the next slot boundary. The warp is serialized with block building, so it never interleaves with an in-flight
+   * build.
+   *
+   * @param duration - Number of seconds to advance; must be positive.
+   * @throws If no automine sequencer is running, or if `duration` is not positive.
+   */
+  warpL2TimeAtLeastBy(duration: number): Promise<void>;
+
+  /**
+   * Registers public function signatures so the node can resolve selectors to names in public-execution stack
+   * traces. The mapping lives only in unpersisted node memory, is not gossiped, and is exposed here (rather than on
+   * the main node API) because it is a debug-only, unauthenticated write that should not be reachable on prod nodes.
+   * @param functionSignatures - Decoded `name(paramTypes)` signatures to register by selector.
+   */
+  registerContractFunctionSignatures(functionSignatures: string[]): Promise<void>;
+}
+
+export const AztecNodeDebugApiSchema: ApiSchemaFor<AztecNodeDebug> = {
+  mineBlock: z.function({ input: z.tuple([]), output: z.void() }),
+  prove: z.function({ input: z.tuple([optional(CheckpointNumberSchema)]), output: CheckpointNumberSchema }),
+  warpL2TimeAtLeastTo: z.function({ input: z.tuple([z.number()]), output: z.void() }),
+  warpL2TimeAtLeastBy: z.function({ input: z.tuple([z.number()]), output: z.void() }),
+  registerContractFunctionSignatures: z.function({
+    input: z.tuple([z.array(z.string().max(MAX_SIGNATURE_LEN)).max(MAX_SIGNATURES_PER_REGISTER_CALL)]),
+    output: z.void(),
+  }),
+};
+
+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 } } : {}),
+  });
+}