@aztec/stdlib 0.0.1-commit.5daedc8 → 0.0.1-commit.6201a7b05

package/src/interfaces/allowed_element.ts

@@ -1,21 +1,43 @@
-import type { Fr } from '@aztec/foundation/fields';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 
 import { z } from 'zod';
 
 import type { FunctionSelector } from '../abi/function_selector.js';
 import type { AztecAddress } from '../aztec-address/index.js';
-import { type ZodFor, schemas } from '../schemas/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 = 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 }),
-]) satisfies ZodFor<AllowedElement>;
+export const AllowedElementSchema = zodFor<AllowedElement>()(
+  z.union([
+    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/api_limit.ts

@@ -1,3 +1,5 @@
 export const MAX_RPC_LEN = 100;
 export const MAX_RPC_TXS_LEN = 50;
 export const MAX_RPC_BLOCKS_LEN = 50;
+export const MAX_RPC_CHECKPOINTS_LEN = 50;
+export const MAX_LOGS_PER_TAG = 10;

package/src/interfaces/archiver.ts

@@ -1,13 +1,18 @@
-import type { L1ContractAddresses } from '@aztec/ethereum';
-import { EpochNumberSchema } from '@aztec/foundation/branded-types';
+import type { L1ContractAddresses } from '@aztec/ethereum/l1-contract-addresses';
+import { BlockNumberSchema, CheckpointNumberSchema, EpochNumberSchema } from '@aztec/foundation/branded-types';
 import type { ApiSchemaFor } from '@aztec/foundation/schemas';
 
 import { z } from 'zod';
 
+import { BlockDataSchema, BlockDataWithCheckpointContextSchema } 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 { PublishedL2Block } from '../block/published_l2_block.js';
-import { ValidateBlockResultSchema } from '../block/validate_block_result.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,
   type ContractDataSource,
@@ -15,7 +20,8 @@ import {
 } from '../contract/index.js';
 import { L1RollupConstantsSchema } from '../epoch-helpers/index.js';
 import { LogFilterSchema } from '../logs/log_filter.js';
-import { PrivateLog } from '../logs/private_log.js';
+import { SiloedTag } from '../logs/siloed_tag.js';
+import { Tag } from '../logs/tag.js';
 import { TxScopedL2Log } from '../logs/tx_scoped_l2_log.js';
 import type { L1ToL2MessageSource } from '../messaging/l1_to_l2_message_source.js';
 import { optional, schemas } from '../schemas/schemas.js';
@@ -48,11 +54,20 @@ export type ArchiverSpecificConfig = {
   /** The maximum possible size of the archiver DB in KB. Overwrites the general dataStoreMapSizeKb. */
   archiverStoreMapSizeKb?: number;
 
-  /** Whether to skip validating block attestations (use only for testing). */
-  skipValidateBlockAttestations?: boolean;
-
   /** 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;
 };
 
 export const ArchiverSpecificConfigSchema = z.object({
@@ -61,8 +76,11 @@ export const ArchiverSpecificConfigSchema = z.object({
   viemPollingIntervalMS: schemas.Integer.optional(),
   maxLogs: schemas.Integer.optional(),
   archiverStoreMapSizeKb: schemas.Integer.optional(),
-  skipValidateBlockAttestations: z.boolean().optional(),
   maxAllowedEthClientDriftSeconds: schemas.Integer.optional(),
+  ethereumAllowNoDebugHosts: z.boolean().optional(),
+  archiverSkipHistoricalLogsCheck: z.boolean().optional(),
+  skipValidateCheckpointAttestations: z.boolean().optional(),
+  skipPromoteProposedCheckpointDuringL1Sync: z.boolean().optional(),
 });
 
 export type ArchiverApi = Omit<
@@ -73,37 +91,63 @@ export type ArchiverApi = Omit<
 export const ArchiverApiSchema: ApiSchemaFor<ArchiverApi> = {
   getRollupAddress: z.function().args().returns(schemas.EthAddress),
   getRegistryAddress: z.function().args().returns(schemas.EthAddress),
-  getBlockNumber: z.function().args().returns(schemas.Integer),
-  getProvenBlockNumber: z.function().args().returns(schemas.Integer),
-  getBlock: z.function().args(schemas.Integer).returns(L2Block.schema.optional()),
+  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
     .function()
-    .args(z.union([schemas.Integer, z.literal('latest')]))
+    .args(z.union([BlockNumberSchema, z.literal('latest')]))
     .returns(BlockHeader.schema.optional()),
-  getBlocks: z
+  getCheckpointedBlock: z.function().args(BlockNumberSchema).returns(CheckpointedL2Block.schema.optional()),
+  getCheckpointedBlocks: z
     .function()
-    .args(schemas.Integer, schemas.Integer, optional(z.boolean()))
-    .returns(z.array(L2Block.schema)),
-  getPublishedBlocks: z
+    .args(BlockNumberSchema, schemas.Integer)
+    .returns(z.array(CheckpointedL2Block.schema)),
+  getBlocks: z.function().args(BlockNumberSchema, schemas.Integer).returns(z.array(L2Block.schema)),
+  getCheckpoints: z
     .function()
-    .args(schemas.Integer, schemas.Integer, optional(z.boolean()))
-    .returns(z.array(PublishedL2Block.schema)),
-  getPublishedBlockByHash: z.function().args(schemas.Fr).returns(PublishedL2Block.schema.optional()),
-  getPublishedBlockByArchive: z.function().args(schemas.Fr).returns(PublishedL2Block.schema.optional()),
-  getBlockHeaderByHash: z.function().args(schemas.Fr).returns(BlockHeader.schema.optional()),
+    .args(CheckpointNumberSchema, schemas.Integer)
+    .returns(z.array(PublishedCheckpoint.schema)),
+  getCheckpointedBlockByHash: z.function().args(BlockHash.schema).returns(CheckpointedL2Block.schema.optional()),
+  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()),
+  getBlockDataWithCheckpointContext: z
+    .function()
+    .args(BlockNumberSchema)
+    .returns(BlockDataWithCheckpointContextSchema.optional()),
+  getCheckpointData: z.function().args(CheckpointNumberSchema).returns(CheckpointDataSchema.optional()),
+  getCheckpointDataRange: z
+    .function()
+    .args(CheckpointNumberSchema, schemas.Integer)
+    .returns(z.array(CheckpointDataSchema)),
+  getCheckpointNumberBySlot: z.function().args(schemas.SlotNumber).returns(CheckpointNumberSchema.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()),
-  getBlocksForEpoch: z.function().args(EpochNumberSchema).returns(z.array(L2Block.schema)),
-  getBlockHeadersForEpoch: z.function().args(EpochNumberSchema).returns(z.array(BlockHeader.schema)),
+  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)),
   isEpochComplete: z.function().args(EpochNumberSchema).returns(z.boolean()),
   getL2Tips: z.function().args().returns(L2TipsSchema),
-  getPrivateLogs: z.function().args(z.number(), z.number()).returns(z.array(PrivateLog.schema)),
-  getLogsByTags: z
+  getPrivateLogsByTags: z
+    .function()
+    .args(z.array(SiloedTag.schema), optional(z.number().gte(0)))
+    .returns(z.array(z.array(TxScopedL2Log.schema))),
+  getPublicLogsByTagsFromContract: z
     .function()
-    .args(z.array(schemas.Fr))
+    .args(schemas.AztecAddress, z.array(Tag.schema), optional(z.number().gte(0)))
     .returns(z.array(z.array(TxScopedL2Log.schema))),
   getPublicLogs: z.function().args(LogFilterSchema).returns(GetPublicLogsResponseSchema),
   getContractClassLogs: z.function().args(LogFilterSchema).returns(GetContractClassLogsResponseSchema),
@@ -115,7 +159,7 @@ export const ArchiverApiSchema: ApiSchemaFor<ArchiverApi> = {
     .returns(ContractInstanceWithAddressSchema.optional()),
   getContractClassIds: z.function().args().returns(z.array(schemas.Fr)),
   registerContractFunctionSignatures: z.function().args(z.array(z.string())).returns(z.void()),
-  getL1ToL2Messages: z.function().args(schemas.Integer).returns(z.array(schemas.Fr)),
+  getL1ToL2Messages: z.function().args(CheckpointNumberSchema).returns(z.array(schemas.Fr)),
   getL1ToL2MessageIndex: z.function().args(schemas.Fr).returns(schemas.BigInt.optional()),
   getDebugFunctionName: z.function().args(schemas.AztecAddress, schemas.FunctionSelector).returns(optional(z.string())),
   getL1Constants: z.function().args().returns(L1RollupConstantsSchema),
@@ -124,7 +168,9 @@ export const ArchiverApiSchema: ApiSchemaFor<ArchiverApi> = {
     .args()
     .returns(z.object({ genesisArchiveRoot: schemas.Fr })),
   getL1Timestamp: z.function().args().returns(schemas.BigInt.optional()),
+  getLastCheckpoint: z.function().args().returns(ProposedCheckpointDataSchema.optional()),
+  getLastProposedCheckpoint: 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(ValidateBlockResultSchema),
+  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,55 +47,80 @@ 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>;
 }
 
-export type AztecNodeAdminConfig = ValidatorClientFullConfig &
+// L1 contracts are not mutable via admin updates.
+export type AztecNodeAdminConfig = Omit<ValidatorClientFullConfig, 'l1Contracts'> &
   SequencerConfig &
   ProverConfig &
   SlasherConfig &
-  Pick<ArchiverSpecificConfig, 'archiverPollingIntervalMS' | 'skipValidateBlockAttestations' | 'archiverBatchSize'> & {
-    maxTxPoolSize: number;
+  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)
+  .merge(ValidatorClientFullConfigSchema.omit({ l1Contracts: true }))
   .merge(
     ArchiverSpecificConfigSchema.pick({
       archiverPollingIntervalMS: true,
-      skipValidateBlockAttestations: true,
       archiverBatchSize: true,
+      skipValidateCheckpointAttestations: true,
     }),
   )
-  .merge(z.object({ maxTxPoolSize: 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()),
+  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 } } : {}),
+  });
+}