@aztec-labs/stdlib 6.0.0-nightly.20260829

package/src/interfaces/block-builder.ts

@@ -0,0 +1,171 @@
+import type { BlockNumber, CheckpointNumber } from '@aztec-labs/foundation/branded-types';
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { LoggerBindings } from '@aztec-labs/foundation/log';
+
+import type { BlockHash } from '../block/block_hash.js';
+import type { L2Block } from '../block/l2_block.js';
+import type { ChainConfig, SequencerConfig } from '../config/chain-config.js';
+import type { L1RollupConstants } from '../epoch-helpers/index.js';
+import type { Gas } from '../gas/gas.js';
+import type { BlockHeader } from '../tx/block_header.js';
+import type { CheckpointGlobalVariables, GlobalVariables } from '../tx/global_variables.js';
+import type { FailedTx, ProcessedTx } from '../tx/processed_tx.js';
+import { Tx } from '../tx/tx.js';
+import type { TxValidator } from '../tx/validator/tx_validator.js';
+import type { MerkleTreeWriteOperations } from './merkle_tree_operations.js';
+import type { ProcessedTxHandler } from './processed-tx-handler.js';
+
+/** The interface to a block builder. Generates an L2 block out of a set of processed txs. */
+export interface IBlockFactory extends ProcessedTxHandler {
+  /**
+   * Prepares to build a new block. Updates the L1 to L2 message tree.
+   * @param globalVariables - The global variables for this block.
+   * @param l1ToL2Messages - The set of L1 to L2 messages to be included in this block.
+   */
+  startNewBlock(globalVariables: GlobalVariables, l1ToL2Messages: Fr[]): Promise<void>;
+
+  /**
+   * Adds all processed txs to the block. Updates world state with the effects from this tx.
+   * @param txs - The transactions to be added.
+   */
+  addTxs(txs: ProcessedTx[]): Promise<void>;
+
+  /**
+   * Assembles the block and updates the archive tree.
+   */
+  setBlockCompleted(expectedBlockHeader?: BlockHeader): Promise<L2Block>;
+}
+
+/** 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. */
+  maxBlockGas?: Gas;
+  /** Maximum number of blob fields allowed. */
+  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;
+  /**
+   * L1-to-L2 message leaves this block consumes, inserted into the fork's L1-to-L2 message tree before the block
+   * header is built. Omitted when the block consumes nothing from the Inbox.
+   */
+  l1ToL2Messages?: Fr[];
+};
+
+/** 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;
+  /** Per-block budget multiplier for DA gas and blob fields. Falls back to perBlockAllocationMultiplier when unset. */
+  perBlockDAAllocationMultiplier?: 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' | 'rollupManaLimit'> &
+  Pick<ChainConfig, 'l1ChainId' | 'rollupVersion'> &
+  Pick<
+    SequencerConfig,
+    | 'txPublicSetupAllowListExtend'
+    | 'fakeProcessingDelayPerTxMs'
+    | 'fakeThrowAfterProcessingTxCount'
+    | 'maxTxsPerBlock'
+    | 'maxTxsPerCheckpoint'
+    | 'maxL2BlockGas'
+    | 'maxDABlockGas'
+  >;
+
+export const FullNodeBlockBuilderConfigKeys: (keyof FullNodeBlockBuilderConfig)[] = [
+  'l1GenesisTime',
+  'slotDuration',
+  'l1ChainId',
+  'rollupVersion',
+  'txPublicSetupAllowListExtend',
+  'fakeProcessingDelayPerTxMs',
+  'fakeThrowAfterProcessingTxCount',
+  'maxTxsPerBlock',
+  'maxTxsPerCheckpoint',
+  'maxL2BlockGas',
+  'maxDABlockGas',
+  'rollupManaLimit',
+] as const;
+
+/** 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';
+  }
+}
+
+/** Result of building a block within a checkpoint. */
+export type BuildBlockInCheckpointResult = {
+  block: L2Block;
+  publicProcessorDuration: number;
+  numTxs: number;
+  failedTxs: FailedTx[];
+  usedTxs: Tx[];
+};
+
+/** 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: BlockBuilderOptions,
+  ): Promise<BuildBlockInCheckpointResult>;
+}
+
+/** Interface for creating checkpoint builders. */
+export interface ICheckpointsBuilder {
+  /**
+   * Syncs world state to `blockNumber` and returns a fork of it at that block. When `blockHash` is
+   * provided it is verified against the synced block, triggering a resync on mismatch (reorg detection).
+   */
+  getFork(blockNumber: BlockNumber, blockHash?: BlockHash): Promise<MerkleTreeWriteOperations>;
+
+  /**
+   * Opens a fresh checkpoint. The checkpoint's L1-to-L2 messages are not passed here: each block carries its own
+   * bundle in `buildBlock`'s `l1ToL2Messages`.
+   */
+  startCheckpoint(
+    checkpointNumber: CheckpointNumber,
+    constants: CheckpointGlobalVariables,
+    feeAssetPriceModifier: bigint,
+    previousCheckpointOutHashes: Fr[],
+    previousInboxRollingHash: Fr,
+    fork: MerkleTreeWriteOperations,
+    bindings?: LoggerBindings,
+  ): Promise<ICheckpointBlockBuilder>;
+}

package/src/interfaces/block_response.ts

@@ -0,0 +1,91 @@
+import {
+  BlockNumberSchema,
+  CheckpointNumberSchema,
+  IndexWithinCheckpointSchema,
+} from '@aztec-labs/foundation/branded-types';
+import type { BlockNumber, CheckpointNumber, IndexWithinCheckpoint } from '@aztec-labs/foundation/branded-types';
+import type { PickIfFlag, Prettify } from '@aztec-labs/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 &
+    PickIfFlag<BlockIncludeOptions, Opts, 'includeTransactions', { body: Body }> &
+    PickIfFlag<BlockIncludeOptions, Opts, 'includeL1PublishInfo', { l1: L1PublishInfo }> &
+    PickIfFlag<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,16 @@
+import { z } from 'zod';
+
+/**
+ * Public checkpoint-tip selectors usable in RPC requests.
+ *
+ * `'proposed'` is intentionally excluded: the proposed-but-unconfirmed checkpoint frontier is an
+ * archiver-internal pipelining concept, not part of the public chain-tip surface. Select the
+ * proposed *block* tip with a block tag (`L2BlockTag`) instead.
+ */
+export type CheckpointTag = 'checkpointed' | 'proven' | 'finalized';
+
+export const CheckpointTagSchema = z.union([
+  z.literal('checkpointed'),
+  z.literal('proven'),
+  z.literal('finalized'),
+]) satisfies z.ZodType<CheckpointTag>;

package/src/interfaces/checkpoint_parameter.ts

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

package/src/interfaces/checkpoint_response.ts

@@ -0,0 +1,83 @@
+import { BlockNumberSchema, CheckpointNumberSchema } from '@aztec-labs/foundation/branded-types';
+import type { BlockNumber, CheckpointNumber } from '@aztec-labs/foundation/branded-types';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { schemas } from '@aztec-labs/foundation/schemas';
+import type { PickIfFlag, Prettify } from '@aztec-labs/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 &
+    PickIfFlag<CheckpointIncludeOptions, Opts, 'includeBlocks', { blocks: BlockResponse<NestedBlockOpts<Opts>>[] }> &
+    PickIfFlag<CheckpointIncludeOptions, Opts, 'includeL1PublishInfo', { l1: L1PublishInfo }> &
+    PickIfFlag<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

@@ -0,0 +1,12 @@
+export * from './aztec-node.js';
+export * from './aztec-node-admin.js';
+export * from './aztec-node-debug.js';
+export { type PeerInfo, type ProposalsForSlot } from './p2p.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 './api_limit.js';
+export * from './public_storage_override.js';

package/src/interfaces/configs.ts

@@ -0,0 +1,223 @@
+import { type SlotNumber, SlotNumberSchema } from '@aztec-labs/foundation/branded-types';
+import type { EthAddress } from '@aztec-labs/foundation/eth-address';
+import type { Prettify } from '@aztec-labs/foundation/types';
+import { z } from 'zod';
+
+import type { AztecAddress } from '../aztec-address/index.js';
+import { schemas, zodFor } from '../schemas/index.js';
+import { type AllowedElement, AllowedElementSchema } from './allowed_element.js';
+
+/** Sequencer configuration */
+export interface SequencerConfig {
+  /** The number of ms to wait between polling for pending txs. */
+  sequencerPollingIntervalMS?: number;
+  /** The maximum number of txs to include in a block. */
+  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. */
+  minValidTxsPerBlock?: number;
+  /** Whether to publish txs with the block proposals */
+  publishTxsWithProposals?: boolean;
+  /** The maximum L2 block gas. */
+  maxL2BlockGas?: number;
+  /** The maximum DA block gas. */
+  maxDABlockGas?: number;
+  /** Per-block gas budget multiplier for both L2 and DA gas. Budget = (checkpointLimit / maxBlocks) * multiplier. */
+  perBlockAllocationMultiplier?: number;
+  /**
+   * Per-block budget multiplier applied to DA gas and blob fields in place of `perBlockAllocationMultiplier`.
+   * Defaults higher than the general multiplier so the largest contract class deploy fits a single block.
+   */
+  perBlockDAAllocationMultiplier?: 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. */
+  feeRecipient?: AztecAddress;
+  /** The working directory to use for simulation/proving */
+  acvmWorkingDirectory?: string;
+  /** The path to the ACVM binary */
+  acvmBinaryPath?: string;
+  /** Additional entries to extend the default setup allow list. */
+  txPublicSetupAllowListExtend?: AllowedElement[];
+  /** Payload address to vote for */
+  governanceProposerPayload?: EthAddress;
+  /**
+   * Keep signalling the configured governance payload even if a proposal referencing it was already
+   * executed within the lookback window. For payloads deliberately designed to be re-executed.
+   */
+  governanceProposerForcePayloadVote?: boolean;
+  /**
+   * Minimum block-building time (`min_block_duration`) still worth allocating if the proposer starts
+   * late, in seconds.
+   */
+  minBlockDuration?: number;
+  /**
+   * Local time (`checkpoint_proposal_prepare_time`) between the last block build finishing and the
+   * checkpoint proposal being ready for p2p send, in seconds.
+   */
+  checkpointProposalPrepareTime?: number;
+  /** How much time (in seconds) we allow in the slot for publishing the L1 tx. */
+  l1PublishingTime?: number;
+  /** Used for testing to introduce a fake delay after processing each tx */
+  fakeProcessingDelayPerTxMs?: number;
+  /** Used for testing to throw an error after processing N txs */
+  fakeThrowAfterProcessingTxCount?: number;
+  /** How many seconds it takes for proposals and attestations to travel across the p2p layer (one-way) */
+  attestationPropagationTime?: number;
+  /** How many seconds before invalidating a block as a committee member (zero to never invalidate) */
+  secondsBeforeInvalidatingBlockAsCommitteeMember?: number;
+  /** How many seconds before invalidating a block as a non-committee member (zero to never invalidate) */
+  secondsBeforeInvalidatingBlockAsNonCommitteeMember?: number;
+  /** Skip collecting attestations (for testing only) */
+  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) */
+  injectHighSValueAttestation?: boolean;
+  /** Inject an attestation with an unrecoverable signature (for testing only) */
+  injectUnrecoverableSignatureAttestation?: boolean;
+  /** Inject a non-proposer attestation slot in yParity (v ∈ {0, 1}) form in the packed L1 tuple (for testing only) */
+  injectYParityAttestation?: boolean;
+  /** Whether to run in fisherman mode: builds blocks on every slot for validation without publishing */
+  fishermanMode?: boolean;
+  /** Shuffle attestation ordering to create invalid ordering (for testing only) */
+  shuffleAttestationOrdering?: boolean;
+  /** Duration per block in milliseconds, used to derive how many blocks fit in a slot (defaults to 3000 ms). */
+  blockDurationMs?: number;
+  /** Consensus grace in seconds for a received checkpoint proposal to materialize into local proposed state. */
+  checkpointProposalSyncGraceSeconds?: number;
+  /** Expected number of block proposals per slot for P2P peer scoring. 0 disables scoring, undefined falls back to blocksPerSlot - 1. */
+  expectedBlockProposalsPerSlot?: number;
+  /** Have sequencer build and publish an empty checkpoint if there are no txs */
+  buildCheckpointIfEmpty?: boolean;
+  /** Skip pushing proposed blocks to archiver (default: false) */
+  skipPushProposedBlocksToArchiver?: boolean;
+  /** Minimum number of blocks required for a checkpoint proposal (test only, defaults to undefined = no minimum) */
+  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[];
+  /**
+   * Minimum number of connected p2p peers required to build and propose a checkpoint. Zero disables the
+   * check. Ignored when p2p is disabled by config.
+   */
+  minPeersToPropose?: number;
+}
+
+export const SequencerConfigSchema = zodFor<SequencerConfig>()(
+  z.object({
+    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(),
+    perBlockDAAllocationMultiplier: z.number().optional(),
+    redistributeCheckpointBudget: z.boolean().optional(),
+    coinbase: schemas.EthAddress.optional(),
+    feeRecipient: schemas.AztecAddress.optional(),
+    acvmWorkingDirectory: z.string().optional(),
+    acvmBinaryPath: z.string().optional(),
+    txPublicSetupAllowListExtend: z.array(AllowedElementSchema).optional(),
+    governanceProposerPayload: schemas.EthAddress.optional(),
+    governanceProposerForcePayloadVote: z.boolean().optional(),
+    minBlockDuration: z.number().positive().optional(),
+    checkpointProposalPrepareTime: z.number().nonnegative().optional(),
+    l1PublishingTime: z.number().optional(),
+    fakeProcessingDelayPerTxMs: z.number().optional(),
+    fakeThrowAfterProcessingTxCount: z.number().optional(),
+    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(),
+    injectYParityAttestation: z.boolean().optional(),
+    fishermanMode: z.boolean().optional(),
+    shuffleAttestationOrdering: z.boolean().optional(),
+    blockDurationMs: z.number().positive().optional(),
+    checkpointProposalSyncGraceSeconds: z.number().nonnegative().optional(),
+    expectedBlockProposalsPerSlot: z.number().nonnegative().optional(),
+    buildCheckpointIfEmpty: z.boolean().optional(),
+    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(),
+    minPeersToPropose: z.number().nonnegative().optional(),
+  }),
+);
+
+type SequencerConfigOptionalKeys =
+  | 'governanceProposerPayload'
+  | 'expectedBlockProposalsPerSlot'
+  | 'coinbase'
+  | 'feeRecipient'
+  | 'acvmWorkingDirectory'
+  | 'acvmBinaryPath'
+  | 'fakeProcessingDelayPerTxMs'
+  | 'fakeThrowAfterProcessingTxCount'
+  | 'minBlockDuration'
+  | 'checkpointProposalPrepareTime'
+  | 'txPublicSetupAllowListExtend'
+  | 'invalidBlockProposalIndexWithinCheckpoint'
+  | 'minValidTxsPerBlock'
+  | 'minBlocksForCheckpoint'
+  | 'maxTxsPerBlock'
+  | 'maxTxsPerCheckpoint'
+  | 'maxL2BlockGas'
+  | 'maxDABlockGas'
+  | 'redistributeCheckpointBudget'
+  | 'skipBroadcastProposals'
+  | 'skipBroadcastCheckpointProposal'
+  | 'pauseProposingForSlots';
+
+export type ResolvedSequencerConfig = Prettify<
+  Required<Omit<SequencerConfig, SequencerConfigOptionalKeys>> & Pick<SequencerConfig, SequencerConfigOptionalKeys>
+>;

package/src/interfaces/get_tx_by_hash_options.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+
+import type { ZodFor } from '../schemas/schemas.js';
+
+/** Options for retrieving txs via {@link AztecNode.getTxByHash} and {@link AztecNode.getTxsByHash}. */
+export type GetTxByHashOptions = {
+  /** Keep the proof on the returned tx; stripped by default. */
+  includeProof?: boolean;
+};
+
+/** Zod schema for {@link GetTxByHashOptions}. */
+export const GetTxByHashOptionsSchema: ZodFor<GetTxByHashOptions> = z.object({
+  includeProof: z.boolean().optional(),
+});

package/src/interfaces/l1_publish_info.ts

@@ -0,0 +1,39 @@
+import { schemas } from '@aztec-labs/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,
+  };
+}