@aztec/stdlib 0.0.1-commit.04852196a → 0.0.1-commit.04d373f

package/src/interfaces/block-builder.ts

@@ -35,7 +35,8 @@ export interface IBlockFactory extends ProcessedTxHandler {
   setBlockCompleted(expectedBlockHeader?: BlockHeader): Promise<L2Block>;
 }
 
-export interface PublicProcessorLimits {
+/** Limits passed to the public processor for tx processing within a block. */
+export type PublicProcessorLimits = {
   /** Maximum number of txs to process. */
   maxTransactions?: number;
   /** L2 and DA gas limits. */
@@ -44,16 +45,41 @@ export interface PublicProcessorLimits {
   maxBlobFields?: number;
   /** Deadline for processing the txs. Processor will stop as soon as it hits this time. */
   deadline?: Date;
+  /** Signal for interrupting processing before the deadline. */
+  signal?: AbortSignal;
   /** Whether this processor is building a proposal (as opposed to re-executing one). Skipping txs due to gas or blob limits is only done during proposal building. */
   isBuildingProposal?: boolean;
-}
+};
+
+/** Base fields shared by both proposer and validator block builder options. */
+type BlockBuilderOptionsBase = PublicProcessorLimits & {
+  /** Minimum number of successfully processed txs required. Block is rejected if fewer succeed. */
+  minValidTxs: number;
+};
+
+/** Proposer mode: redistribution params are required. */
+type ProposerBlockBuilderOptions = BlockBuilderOptionsBase & {
+  isBuildingProposal: true;
+  /** Maximum number of blocks per checkpoint, derived from the timetable. */
+  maxBlocksPerCheckpoint: number;
+  /** Per-block gas budget multiplier. Budget = (remaining / remainingBlocks) * multiplier. */
+  perBlockAllocationMultiplier: number;
+};
+
+/** Validator mode: no redistribution params needed. */
+type ValidatorBlockBuilderOptions = BlockBuilderOptionsBase & {
+  isBuildingProposal: false;
+};
+
+/** Options for building a block within a checkpoint. When proposing, redistribution params are required. */
+export type BlockBuilderOptions = ProposerBlockBuilderOptions | ValidatorBlockBuilderOptions;
 
 export interface PublicProcessorValidator {
   preprocessValidator?: TxValidator<Tx>;
   nullifierCache?: { addNullifiers: (nullifiers: Buffer[]) => void };
 }
 
-export type FullNodeBlockBuilderConfig = Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration'> &
+export type FullNodeBlockBuilderConfig = Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'rollupManaLimit'> &
   Pick<ChainConfig, 'l1ChainId' | 'rollupVersion'> &
   Pick<
     SequencerConfig,
@@ -64,10 +90,7 @@ export type FullNodeBlockBuilderConfig = Pick<L1RollupConstants, 'l1GenesisTime'
     | 'maxTxsPerCheckpoint'
     | 'maxL2BlockGas'
     | 'maxDABlockGas'
-  > & {
-    /** Total L2 gas (mana) allowed per checkpoint. Fetched from L1 getManaLimit(). */
-    rollupManaLimit: number;
-  };
+  >;
 
 export const FullNodeBlockBuilderConfigKeys: (keyof FullNodeBlockBuilderConfig)[] = [
   'l1GenesisTime',
@@ -84,11 +107,15 @@ export const FullNodeBlockBuilderConfigKeys: (keyof FullNodeBlockBuilderConfig)[
   'rollupManaLimit',
 ] as const;
 
-/** Thrown when no valid transactions are available to include in a block after processing, and this is not the first block in a checkpoint. */
-export class NoValidTxsError extends Error {
-  constructor(public readonly failedTxs: FailedTx[]) {
-    super('No valid transactions to include in block');
-    this.name = 'NoValidTxsError';
+/** Thrown when the number of successfully processed transactions is below the required minimum. */
+export class InsufficientValidTxsError extends Error {
+  constructor(
+    public readonly processedCount: number,
+    public readonly minRequired: number,
+    public readonly failedTxs: FailedTx[],
+  ) {
+    super(`Insufficient valid txs: got ${processedCount} but need ${minRequired}`);
+    this.name = 'InsufficientValidTxsError';
   }
 }
 
@@ -103,11 +130,12 @@ export type BuildBlockInCheckpointResult = {
 
 /** Interface for building blocks within a checkpoint context. */
 export interface ICheckpointBlockBuilder {
+  /** Builds a single block within this checkpoint. Throws InsufficientValidTxsError if fewer than minValidTxs succeed. */
   buildBlock(
     pendingTxs: Iterable<Tx> | AsyncIterable<Tx>,
     blockNumber: BlockNumber,
     timestamp: bigint,
-    opts: PublicProcessorLimits,
+    opts: BlockBuilderOptions,
   ): Promise<BuildBlockInCheckpointResult>;
 }
 

package/src/interfaces/block_response.ts

@@ -0,0 +1,92 @@
+import {
+  BlockNumberSchema,
+  CheckpointNumberSchema,
+  IndexWithinCheckpointSchema,
+} from '@aztec/foundation/branded-types';
+import type { BlockNumber, CheckpointNumber, IndexWithinCheckpoint } from '@aztec/foundation/branded-types';
+import type { IfFlag, Prettify } from '@aztec/foundation/types';
+
+import { z } from 'zod';
+
+import { BlockHash } from '../block/block_hash.js';
+import { Body } from '../block/body.js';
+import { CommitteeAttestation } from '../block/proposal/committee_attestation.js';
+import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
+import { BlockHeader } from '../tx/block_header.js';
+import { type L1PublishInfo, L1PublishInfoSchema } from './l1_publish_info.js';
+
+/** Options for narrowing the response of `getBlock`. */
+export type BlockIncludeOptions = {
+  /** Include the block body (tx effects). Off by default. */
+  includeTransactions?: boolean;
+  /** Include L1 publish info (populated with `published: false` if not yet on L1). Off by default. */
+  includeL1PublishInfo?: boolean;
+  /** Include committee attestations. Empty array until the block's checkpoint is published. Off by default. */
+  includeAttestations?: boolean;
+};
+
+export const BlockIncludeOptionsSchema: z.ZodType<BlockIncludeOptions> = z.object({
+  includeTransactions: z.boolean().optional(),
+  includeL1PublishInfo: z.boolean().optional(),
+  includeAttestations: z.boolean().optional(),
+});
+
+/** Options for narrowing the response of `getBlocks` (range). Extends single-block options with range-only flags. */
+export type BlocksIncludeOptions = BlockIncludeOptions & {
+  /** Only return blocks that belong to a confirmed L1 checkpoint. Off by default. */
+  onlyCheckpointed?: boolean;
+};
+
+export const BlocksIncludeOptionsSchema: z.ZodType<BlocksIncludeOptions> = z.object({
+  includeTransactions: z.boolean().optional(),
+  includeL1PublishInfo: z.boolean().optional(),
+  includeAttestations: z.boolean().optional(),
+  onlyCheckpointed: z.boolean().optional(),
+});
+
+/** Required metadata always present on a {@link BlockResponse}. */
+export type BlockResponseBase = {
+  /** Block header. */
+  header: BlockHeader;
+  /** Archive tree snapshot after this block. */
+  archive: AppendOnlyTreeSnapshot;
+  /** Hash of the block header. */
+  hash: BlockHash;
+  /** Checkpoint number this block belongs to. */
+  checkpointNumber: CheckpointNumber;
+  /** Position of the block within its checkpoint. */
+  indexWithinCheckpoint: IndexWithinCheckpoint;
+  /** L2 block number. */
+  number: BlockNumber;
+};
+
+/**
+ * RPC-surface representation of an L2 block.
+ *
+ * Generic over the include-options so that flagged fields become required when the caller passes a
+ * literal `true`. The default type argument ({@link BlockIncludeOptions}) yields the widest shape
+ * (all include-fields optional) — this is what the JSON-RPC wire layer validates against.
+ *
+ * @example
+ * const b: BlockResponse<{ includeTransactions: true }> = await node.getBlock(1, { includeTransactions: true });
+ * b.body; // required, not optional
+ */
+export type BlockResponse<Opts extends BlockIncludeOptions = BlockIncludeOptions> = Prettify<
+  BlockResponseBase &
+    IfFlag<BlockIncludeOptions, Opts, 'includeTransactions', { body: Body }> &
+    IfFlag<BlockIncludeOptions, Opts, 'includeL1PublishInfo', { l1: L1PublishInfo }> &
+    IfFlag<BlockIncludeOptions, Opts, 'includeAttestations', { attestations: CommitteeAttestation[] }>
+>;
+
+/** Zod schema for the widest {@link BlockResponse} shape (all include-gated fields optional). */
+export const BlockResponseSchema = z.object({
+  header: BlockHeader.schema,
+  archive: AppendOnlyTreeSnapshot.schema,
+  hash: BlockHash.schema,
+  checkpointNumber: CheckpointNumberSchema,
+  indexWithinCheckpoint: IndexWithinCheckpointSchema,
+  number: BlockNumberSchema,
+  body: Body.schema.optional(),
+  l1: L1PublishInfoSchema.optional(),
+  attestations: z.array(CommitteeAttestation.schema).optional(),
+});

package/src/interfaces/chain_tips.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+
+import { type L2BlockTag, type L2Tips, L2TipsSchema } from '../block/l2_block_source.js';
+
+/**
+ * Public chain-tip selectors usable in RPC requests.
+ * Omits internal-only tags (e.g. `proposedCheckpoint`) from {@link L2BlockTag}.
+ */
+export type ChainTip = Exclude<L2BlockTag, 'proposedCheckpoint'>;
+
+export const ChainTipSchema = z.union([
+  z.literal('proposed'),
+  z.literal('checkpointed'),
+  z.literal('proven'),
+  z.literal('finalized'),
+]) satisfies z.ZodType<ChainTip>;
+
+/**
+ * Tips of the L2 chain.
+ * Omits the sequencer-internal `proposedCheckpoint` from the public RPC surface.
+ */
+export type ChainTips = Omit<L2Tips, 'proposedCheckpoint'>;
+
+export const ChainTipsSchema = L2TipsSchema.omit({ proposedCheckpoint: true });

package/src/interfaces/checkpoint_parameter.ts

@@ -0,0 +1,20 @@
+import { CheckpointNumberSchema, SlotNumberSchema } from '@aztec/foundation/branded-types';
+
+import { z } from 'zod';
+
+import { ChainTipSchema } from './chain_tips.js';
+
+/**
+ * Selector for a checkpoint in RPC calls.
+ *
+ * Accepts a numeric checkpoint number (or `{ number }`), a slot number (`{ slot }`),
+ * or a chain-tip name (e.g. `'proposed'`, `'proven'`).
+ */
+export const CheckpointParameterSchema = z.union([
+  z.object({ number: CheckpointNumberSchema }).strict(),
+  z.object({ slot: SlotNumberSchema }).strict(),
+  ChainTipSchema,
+  CheckpointNumberSchema,
+]);
+
+export type CheckpointParameter = z.infer<typeof CheckpointParameterSchema>;

package/src/interfaces/checkpoint_response.ts

@@ -0,0 +1,84 @@
+import { BlockNumberSchema, CheckpointNumberSchema } from '@aztec/foundation/branded-types';
+import type { BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { schemas } from '@aztec/foundation/schemas';
+import type { IfFlag, Prettify } from '@aztec/foundation/types';
+
+import { z } from 'zod';
+
+import { CommitteeAttestation } from '../block/proposal/committee_attestation.js';
+import { CheckpointHeader } from '../rollup/checkpoint_header.js';
+import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
+import { type BlockResponse, BlockResponseSchema } from './block_response.js';
+import { type L1PublishInfo, L1PublishInfoSchema } from './l1_publish_info.js';
+
+/** Options for narrowing the response of `getCheckpoint` / `getCheckpoints`. */
+export type CheckpointIncludeOptions = {
+  /** Include the nested blocks. Off by default. */
+  includeBlocks?: boolean;
+  /** When `includeBlocks` is true, include each block's body (tx effects). Off by default. No-op if `includeBlocks` is false. */
+  includeTransactions?: boolean;
+  /** Include L1 publish info. Off by default. */
+  includeL1PublishInfo?: boolean;
+  /** Include committee attestations. Off by default. */
+  includeAttestations?: boolean;
+};
+
+export const CheckpointIncludeOptionsSchema: z.ZodType<CheckpointIncludeOptions> = z.object({
+  includeBlocks: z.boolean().optional(),
+  includeTransactions: z.boolean().optional(),
+  includeL1PublishInfo: z.boolean().optional(),
+  includeAttestations: z.boolean().optional(),
+});
+
+/** Required metadata always present on a {@link CheckpointResponse}. */
+export type CheckpointResponseBase = {
+  /** Checkpoint number. */
+  number: CheckpointNumber;
+  /** Checkpoint header. */
+  header: CheckpointHeader;
+  /** Archive tree snapshot after this checkpoint. */
+  archive: AppendOnlyTreeSnapshot;
+  /** Hash of the checkpoint out messages. */
+  checkpointOutHash: Fr;
+  /** First block number in this checkpoint. */
+  startBlock: BlockNumber;
+  /** Number of blocks in this checkpoint. */
+  blockCount: number;
+  /** Fee asset price modifier in basis points applied during this checkpoint. */
+  feeAssetPriceModifier: bigint;
+};
+
+// Only forward `includeTransactions` to nested blocks — the other include-flags on the checkpoint
+// options do not apply to the nested block responses (those carry no independent L1 / attestations).
+type NestedBlockOpts<Opts> = Opts extends { includeTransactions: true } ? { includeTransactions: true } : {};
+
+/**
+ * RPC-surface representation of an L2 checkpoint.
+ *
+ * Generic over the include-options so that flagged fields become required when the caller passes a
+ * literal `true`. Only `includeTransactions` is forwarded to nested blocks, so
+ * `includeL1PublishInfo` / `includeAttestations` on a checkpoint request do not imply the same on
+ * its nested blocks. The default type argument ({@link CheckpointIncludeOptions}) yields the
+ * widest shape — what the JSON-RPC wire layer validates against.
+ */
+export type CheckpointResponse<Opts extends CheckpointIncludeOptions = CheckpointIncludeOptions> = Prettify<
+  CheckpointResponseBase &
+    IfFlag<CheckpointIncludeOptions, Opts, 'includeBlocks', { blocks: BlockResponse<NestedBlockOpts<Opts>>[] }> &
+    IfFlag<CheckpointIncludeOptions, Opts, 'includeL1PublishInfo', { l1: L1PublishInfo }> &
+    IfFlag<CheckpointIncludeOptions, Opts, 'includeAttestations', { attestations: CommitteeAttestation[] }>
+>;
+
+/** Zod schema for the widest {@link CheckpointResponse} shape (all include-gated fields optional). */
+export const CheckpointResponseSchema = z.object({
+  number: CheckpointNumberSchema,
+  header: CheckpointHeader.schema,
+  archive: AppendOnlyTreeSnapshot.schema,
+  checkpointOutHash: schemas.Fr,
+  startBlock: BlockNumberSchema,
+  blockCount: z.number(),
+  feeAssetPriceModifier: schemas.BigInt,
+  blocks: z.array(BlockResponseSchema).optional(),
+  l1: L1PublishInfoSchema.optional(),
+  attestations: z.array(CommitteeAttestation.schema).optional(),
+});

package/src/interfaces/client.ts

@@ -1,5 +1,11 @@
 export * from './aztec-node.js';
 export * from './aztec-node-admin.js';
+export * from './aztec-node-debug.js';
+export * from './block_response.js';
+export * from './chain_tips.js';
+export * from './checkpoint_parameter.js';
+export * from './checkpoint_response.js';
+export * from './l1_publish_info.js';
 export * from './private_kernel_prover.js';
-export * from './get_logs_response.js';
 export * from './api_limit.js';
+export * from './public_storage_override.js';

package/src/interfaces/configs.ts

@@ -1,3 +1,4 @@
+import { type SlotNumber, SlotNumberSchema } from '@aztec/foundation/branded-types';
 import type { EthAddress } from '@aztec/foundation/eth-address';
 import type { Prettify } from '@aztec/foundation/types';
 
@@ -15,6 +16,8 @@ export interface SequencerConfig {
   maxTxsPerBlock?: number;
   /** The maximum number of txs across all blocks in a checkpoint. */
   maxTxsPerCheckpoint?: number;
+  /** Maximum number of blocks the sequencer packs into a single checkpoint, and the highest indexWithinCheckpoint accepted on a block proposal. */
+  maxBlocksPerCheckpoint?: number;
   /** The minimum number of txs to include in a block. */
   minTxsPerBlock?: number;
   /** The minimum number of valid txs (after execution) to include in a block. If not set, falls back to minTxsPerBlock. */
@@ -27,6 +30,8 @@ export interface SequencerConfig {
   maxDABlockGas?: number;
   /** Per-block gas budget multiplier for both L2 and DA gas. Budget = (checkpointLimit / maxBlocks) * multiplier. */
   perBlockAllocationMultiplier?: number;
+  /** Redistribute remaining checkpoint budget evenly across remaining blocks instead of allowing a single block to consume the entire remaining budget. */
+  redistributeCheckpointBudget?: boolean;
   /** Recipient of block reward. */
   coinbase?: EthAddress;
   /** Address to receive fees. */
@@ -57,8 +62,21 @@ export interface SequencerConfig {
   skipCollectingAttestations?: boolean;
   /** Do not invalidate the previous block if invalid when we are the proposer (for testing only) */
   skipInvalidateBlockAsProposer?: boolean;
+  /**
+   * Bypass the parent checkpoint validity check before submitting a pipelined checkpoint, allowing
+   * the proposer to publish even when the parent landed on L1 with invalid attestations (for testing only).
+   */
+  skipWaitForValidParentCheckpointOnL1?: boolean;
   /** Broadcast invalid block proposals with corrupted state (for testing only) */
   broadcastInvalidBlockProposal?: boolean;
+  /** Broadcast an invalid block proposal only at this indexWithinCheckpoint (for testing only) */
+  invalidBlockProposalIndexWithinCheckpoint?: number;
+  /**
+   * Broadcast invalid checkpoint proposals (with corrupted archive) while keeping the underlying
+   * block proposals valid (for testing only). When unset, the checkpoint follows
+   * `broadcastInvalidBlockProposal`.
+   */
+  broadcastInvalidCheckpointProposalOnly?: boolean;
   /** Inject a fake attestation (for testing only) */
   injectFakeAttestation?: boolean;
   /** Inject a malleable attestation with a high-s value (for testing only) */
@@ -81,6 +99,18 @@ export interface SequencerConfig {
   minBlocksForCheckpoint?: number;
   /** Skip publishing checkpoint proposals probability (for testing checkpoint prunes only) */
   skipPublishingCheckpointsPercent?: number;
+  /** Skip broadcasting checkpoint and block proposals via gossipsub when proposer (for testing only) */
+  skipBroadcastProposals?: boolean;
+  /**
+   * Skip broadcasting only the CheckpointProposal via gossipsub when proposer; the held last block is still broadcast
+   * standalone so peers receive it as a proposed-but-uncheckpointed tip. Used to exercise the orphan-proposed-block
+   * prune path (for testing only). Narrower variant of `skipBroadcastProposals`: when only this flag is set the held
+   * last block is still broadcast standalone, but when `skipBroadcastProposals` is also set neither the block nor the
+   * checkpoint proposal is broadcast.
+   */
+  skipBroadcastCheckpointProposal?: boolean;
+  /** List of slots for which the sequencer will not produce a proposal (for testing only). Attestation paths are unaffected. */
+  pauseProposingForSlots?: SlotNumber[];
 }
 
 export const SequencerConfigSchema = zodFor<SequencerConfig>()(
@@ -88,12 +118,14 @@ export const SequencerConfigSchema = zodFor<SequencerConfig>()(
     sequencerPollingIntervalMS: z.number().optional(),
     maxTxsPerBlock: z.number().optional(),
     maxTxsPerCheckpoint: z.number().optional(),
+    maxBlocksPerCheckpoint: z.number().positive().optional(),
     minValidTxsPerBlock: z.number().optional(),
     minTxsPerBlock: z.number().optional(),
     maxL2BlockGas: z.number().optional(),
     publishTxsWithProposals: z.boolean().optional(),
     maxDABlockGas: z.number().optional(),
     perBlockAllocationMultiplier: z.number().optional(),
+    redistributeCheckpointBudget: z.boolean().optional(),
     coinbase: schemas.EthAddress.optional(),
     feeRecipient: schemas.AztecAddress.optional(),
     acvmWorkingDirectory: z.string().optional(),
@@ -107,9 +139,12 @@ export const SequencerConfigSchema = zodFor<SequencerConfig>()(
     attestationPropagationTime: z.number().optional(),
     skipCollectingAttestations: z.boolean().optional(),
     skipInvalidateBlockAsProposer: z.boolean().optional(),
+    skipWaitForValidParentCheckpointOnL1: z.boolean().optional(),
     secondsBeforeInvalidatingBlockAsCommitteeMember: z.number(),
     secondsBeforeInvalidatingBlockAsNonCommitteeMember: z.number(),
     broadcastInvalidBlockProposal: z.boolean().optional(),
+    invalidBlockProposalIndexWithinCheckpoint: z.number().int().nonnegative().optional(),
+    broadcastInvalidCheckpointProposalOnly: z.boolean().optional(),
     injectFakeAttestation: z.boolean().optional(),
     injectHighSValueAttestation: z.boolean().optional(),
     injectUnrecoverableSignatureAttestation: z.boolean().optional(),
@@ -121,6 +156,9 @@ export const SequencerConfigSchema = zodFor<SequencerConfig>()(
     skipPushProposedBlocksToArchiver: z.boolean().optional(),
     minBlocksForCheckpoint: z.number().positive().optional(),
     skipPublishingCheckpointsPercent: z.number().gte(0).lte(100).optional(),
+    skipBroadcastProposals: z.boolean().optional(),
+    skipBroadcastCheckpointProposal: z.boolean().optional(),
+    pauseProposingForSlots: z.array(SlotNumberSchema).optional(),
   }),
 );
 
@@ -136,13 +174,17 @@ type SequencerConfigOptionalKeys =
   | 'fakeThrowAfterProcessingTxCount'
   | 'l1PublishingTime'
   | 'txPublicSetupAllowListExtend'
+  | 'invalidBlockProposalIndexWithinCheckpoint'
   | 'minValidTxsPerBlock'
   | 'minBlocksForCheckpoint'
   | 'maxTxsPerBlock'
   | 'maxTxsPerCheckpoint'
   | 'maxL2BlockGas'
   | 'maxDABlockGas'
-  | 'perBlockAllocationMultiplier';
+  | 'redistributeCheckpointBudget'
+  | 'skipBroadcastProposals'
+  | 'skipBroadcastCheckpointProposal'
+  | 'pauseProposingForSlots';
 
 export type ResolvedSequencerConfig = Prettify<
   Required<Omit<SequencerConfig, SequencerConfigOptionalKeys>> & Pick<SequencerConfig, SequencerConfigOptionalKeys>

package/src/interfaces/l1_publish_info.ts

@@ -0,0 +1,40 @@
+import { schemas } from '@aztec/foundation/schemas';
+
+import { z } from 'zod';
+
+import { L1PublishedData } from '../checkpoint/published_checkpoint.js';
+
+/**
+ * L1 publication info for a block or checkpoint.
+ *
+ * A discriminated union over `published`: when `false`, the block/checkpoint has not yet been
+ * published to L1. When `true`, the L1 block info (number, timestamp, hash) is present.
+ *
+ * Distinct from {@link L1PublishedData}, which is always the "published" case.
+ */
+export type L1PublishInfo =
+  | { published: false }
+  | { published: true; blockNumber: bigint; timestamp: bigint; blockHash: string };
+
+export const L1PublishInfoSchema = z.union([
+  z.object({ published: z.literal(false) }),
+  z.object({
+    published: z.literal(true),
+    blockNumber: schemas.BigInt,
+    timestamp: schemas.BigInt,
+    blockHash: z.string(),
+  }),
+]);
+
+/** Projects the internal {@link L1PublishedData} (or its absence) to the public {@link L1PublishInfo} shape. */
+export function l1PublishInfoFromL1PublishedData(data: L1PublishedData | undefined): L1PublishInfo {
+  if (!data) {
+    return { published: false };
+  }
+  return {
+    published: true,
+    blockNumber: data.blockNumber,
+    timestamp: data.timestamp,
+    blockHash: data.blockHash,
+  };
+}

package/src/interfaces/l2_logs_source.ts

@@ -1,54 +1,28 @@
 import type { BlockNumber } from '@aztec/foundation/branded-types';
 
-import type { AztecAddress } from '../aztec-address/index.js';
-import type { LogFilter } from '../logs/log_filter.js';
-import type { SiloedTag } from '../logs/siloed_tag.js';
-import type { Tag } from '../logs/tag.js';
-import type { TxScopedL2Log } from '../logs/tx_scoped_l2_log.js';
-import type { GetContractClassLogsResponse, GetPublicLogsResponse } from './get_logs_response.js';
+import type { LogResult } from '../logs/log_result.js';
+import type { PrivateLogsQuery, PublicLogsQuery } from '../logs/logs_query.js';
 
 /**
  * Interface of classes allowing for the retrieval of logs.
+ *
+ * The return type is always the widest {@link LogResult} shape (noteHashes/nullifiers optional). To
+ * narrow at the call site after passing `includeEffects: true`, use the typed wrapper functions in
+ * `pxe/src/tagging/get_all_logs_by_tags.ts` (or cast — the wire payload is the widest shape, so a
+ * stricter generic on this interface would not survive the JSON-RPC boundary anyway).
  */
 export interface L2LogsSource {
   /**
-   * Gets private logs that match any of the `tags`. For each tag, an array of matching logs is returned. An empty
-   * array implies no logs match that tag.
-   * @param tags - The tags to search for.
-   * @param page - The page number (0-indexed) for pagination.
-   * @returns An array of log arrays, one per tag. Returns at most 10 logs per tag per page. If 10 logs are returned
-   * for a tag, the caller should fetch the next page to check for more logs.
+   * Gets private logs matching the given tags. Returns one inner array per element of `query.tags`, in
+   * input order. An empty inner array means no logs matched that tag.
    */
-  getPrivateLogsByTags(tags: SiloedTag[], page?: number): Promise<TxScopedL2Log[][]>;
+  getPrivateLogsByTags(query: PrivateLogsQuery): Promise<LogResult[][]>;
 
   /**
-   * Gets public logs that match any of the `tags` from the specified contract. For each tag, an array of matching
-   * logs is returned. An empty array implies no logs match that tag.
-   * @param contractAddress - The contract address to search logs for.
-   * @param tags - The tags to search for.
-   * @param page - The page number (0-indexed) for pagination.
-   * @returns An array of log arrays, one per tag. Returns at most 10 logs per tag per page. If 10 logs are returned
-   * for a tag, the caller should fetch the next page to check for more logs.
+   * Gets public logs matching the given tags for the given contract. Returns one inner array per element
+   * of `query.tags`, in input order. An empty inner array means no logs matched that tag.
    */
-  getPublicLogsByTagsFromContract(
-    contractAddress: AztecAddress,
-    tags: Tag[],
-    page?: number,
-  ): Promise<TxScopedL2Log[][]>;
-
-  /**
-   * Gets public logs based on the provided filter.
-   * @param filter - The filter to apply to the logs.
-   * @returns The requested logs.
-   */
-  getPublicLogs(filter: LogFilter): Promise<GetPublicLogsResponse>;
-
-  /**
-   * Gets contract class logs based on the provided filter.
-   * @param filter - The filter to apply to the logs.
-   * @returns The requested logs.
-   */
-  getContractClassLogs(filter: LogFilter): Promise<GetContractClassLogsResponse>;
+  getPublicLogsByTags(query: PublicLogsQuery): Promise<LogResult[][]>;
 
   /**
    * Gets the number of the latest L2 block processed by the implementation.

package/src/interfaces/merkle_tree_operations.ts

@@ -3,6 +3,7 @@ import type { Fr } from '@aztec/foundation/curves/bn254';
 import { createLogger } from '@aztec/foundation/log';
 import { type IndexedTreeLeafPreimage, SiblingPath } from '@aztec/foundation/trees';
 
+import type { BlockHash } from '../block/block_hash.js';
 import type { MerkleTreeId, TreeHeights } from '../trees/merkle_tree_id.js';
 import type { NullifierLeaf } from '../trees/nullifier_leaf.js';
 import type { PublicDataTreeLeaf } from '../trees/public_data_leaf.js';
@@ -99,7 +100,7 @@ type LeafTypes = {
   [MerkleTreeId.NOTE_HASH_TREE]: Fr;
   [MerkleTreeId.PUBLIC_DATA_TREE]: Buffer;
   [MerkleTreeId.L1_TO_L2_MESSAGE_TREE]: Fr;
-  [MerkleTreeId.ARCHIVE]: Fr;
+  [MerkleTreeId.ARCHIVE]: BlockHash;
 };
 
 type LeafValueTypes = {
@@ -107,7 +108,7 @@ type LeafValueTypes = {
   [MerkleTreeId.NOTE_HASH_TREE]: Fr;
   [MerkleTreeId.PUBLIC_DATA_TREE]: PublicDataTreeLeaf;
   [MerkleTreeId.L1_TO_L2_MESSAGE_TREE]: Fr;
-  [MerkleTreeId.ARCHIVE]: Fr;
+  [MerkleTreeId.ARCHIVE]: BlockHash;
 };
 
 export type MerkleTreeLeafType<ID extends MerkleTreeId> = LeafTypes[ID];
@@ -225,30 +226,20 @@ export interface MerkleTreeReadOperations {
 }
 
 export interface MerkleTreeCheckpointOperations {
-  /**
-   * Checkpoints the current fork state
-   */
-  createCheckpoint(): Promise<void>;
+  /** Checkpoints the current fork state. Returns the depth of the new checkpoint. */
+  createCheckpoint(): Promise<number>;
 
-  /**
-   * Commits the current checkpoint
-   */
+  /** Commits the current checkpoint. */
   commitCheckpoint(): Promise<void>;
 
-  /**
-   * Reverts the current checkpoint
-   */
+  /** Reverts the current checkpoint. */
   revertCheckpoint(): Promise<void>;
 
-  /**
-   * Commits all checkpoints
-   */
-  commitAllCheckpoints(): Promise<void>;
+  /** Commits all checkpoints above the given depth, leaving checkpoint depth at the given value. */
+  commitAllCheckpointsTo(depth: number): Promise<void>;
 
-  /**
-   * Reverts all checkpoints
-   */
-  revertAllCheckpoints(): Promise<void>;
+  /** Reverts all checkpoints above the given depth, leaving checkpoint depth at the given value. */
+  revertAllCheckpointsTo(depth: number): Promise<void>;
 }
 
 export interface MerkleTreeWriteOperations

package/src/interfaces/p2p-bootstrap.ts

@@ -16,6 +16,6 @@ export interface P2PBootstrapApi {
 }
 
 export const P2PBootstrapApiSchema: ApiSchemaFor<P2PBootstrapApi> = {
-  getEncodedEnr: z.function().returns(z.string()),
-  getRoutingTable: z.function().returns(z.array(z.string())),
+  getEncodedEnr: z.function({ input: z.tuple([]), output: z.string() }),
+  getRoutingTable: z.function({ input: z.tuple([]), output: z.array(z.string()) }),
 };