@aztec/stdlib 0.0.0-test.0 → 0.0.1-commit.0208eb9

package/src/interfaces/server_circuit_prover.ts

@@ -1,27 +1,41 @@
 import type {
-  AVM_PROOF_LENGTH_IN_FIELDS,
+  AVM_V2_PROOF_LENGTH_IN_FIELDS_PADDED,
   NESTED_RECURSIVE_PROOF_LENGTH,
   NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH,
   RECURSIVE_PROOF_LENGTH,
-  TUBE_PROOF_LENGTH,
 } from '@aztec/constants';
 
 import type { AvmCircuitInputs } from '../avm/avm.js';
-import type { BaseParityInputs } from '../parity/base_parity_inputs.js';
+import type { ParityBasePrivateInputs } from '../parity/parity_base_private_inputs.js';
 import type { ParityPublicInputs } from '../parity/parity_public_inputs.js';
-import type { RootParityInputs } from '../parity/root_parity_inputs.js';
-import type { BaseOrMergeRollupPublicInputs } from '../rollup/base_or_merge_rollup_public_inputs.js';
-import type { BlockMergeRollupInputs } from '../rollup/block_merge_rollup.js';
-import type { BlockRootOrBlockMergePublicInputs } from '../rollup/block_root_or_block_merge_public_inputs.js';
-import type { BlockRootRollupInputs, SingleTxBlockRootRollupInputs } from '../rollup/block_root_rollup.js';
-import type { EmptyBlockRootRollupInputs } from '../rollup/empty_block_root_rollup_inputs.js';
-import type { MergeRollupInputs } from '../rollup/merge_rollup.js';
-import type { PrivateBaseRollupInputs } from '../rollup/private_base_rollup_inputs.js';
-import type { PublicBaseRollupInputs } from '../rollup/public_base_rollup_inputs.js';
-import type { RootRollupInputs, RootRollupPublicInputs } from '../rollup/root_rollup.js';
-import type { TubeInputs } from '../rollup/tube_inputs.js';
+import type { ParityRootPrivateInputs } from '../parity/parity_root_private_inputs.js';
+import type { RecursiveProof } from '../proofs/recursive_proof.js';
+import type { BlockMergeRollupPrivateInputs } from '../rollup/block_merge_rollup_private_inputs.js';
+import type { BlockRollupPublicInputs } from '../rollup/block_rollup_public_inputs.js';
+import type {
+  BlockRootEmptyTxFirstRollupPrivateInputs,
+  BlockRootFirstRollupPrivateInputs,
+  BlockRootRollupPrivateInputs,
+  BlockRootSingleTxFirstRollupPrivateInputs,
+  BlockRootSingleTxRollupPrivateInputs,
+} from '../rollup/block_root_rollup_private_inputs.js';
+import type { CheckpointMergeRollupPrivateInputs } from '../rollup/checkpoint_merge_rollup_private_inputs.js';
+import type { CheckpointRollupPublicInputs } from '../rollup/checkpoint_rollup_public_inputs.js';
+import type {
+  CheckpointPaddingRollupPrivateInputs,
+  CheckpointRootRollupPrivateInputs,
+  CheckpointRootSingleBlockRollupPrivateInputs,
+} from '../rollup/checkpoint_root_rollup_private_inputs.js';
+import type { PrivateTxBaseRollupPrivateInputs } from '../rollup/private_tx_base_rollup_private_inputs.js';
+import type { PublicChonkVerifierPrivateInputs } from '../rollup/public_chonk_verifier_private_inputs.js';
+import type { PublicChonkVerifierPublicInputs } from '../rollup/public_chonk_verifier_public_inputs.js';
+import type { PublicTxBaseRollupPrivateInputs } from '../rollup/public_tx_base_rollup_private_inputs.js';
+import type { RootRollupPrivateInputs } from '../rollup/root_rollup_private_inputs.js';
+import type { RootRollupPublicInputs } from '../rollup/root_rollup_public_inputs.js';
+import type { TxMergeRollupPrivateInputs } from '../rollup/tx_merge_rollup_private_inputs.js';
+import type { TxRollupPublicInputs } from '../rollup/tx_rollup_public_inputs.js';
 import type { Tx } from '../tx/tx.js';
-import type { ProofAndVerificationKey, PublicInputsAndRecursiveProof } from './proving-job.js';
+import type { PublicInputsAndRecursiveProof } from './proving-job.js';
 
 /**
  * Generates proofs for parity and rollup circuits.
@@ -32,7 +46,7 @@ export interface ServerCircuitProver {
    * @param input - Input to the circuit.
    */
   getBaseParityProof(
-    inputs: BaseParityInputs,
+    inputs: ParityBasePrivateInputs,
     signal?: AbortSignal,
     epochNumber?: number,
   ): Promise<PublicInputsAndRecursiveProof<ParityPublicInputs, typeof RECURSIVE_PROOF_LENGTH>>;
@@ -42,95 +56,119 @@ export interface ServerCircuitProver {
    * @param input - Input to the circuit.
    */
   getRootParityProof(
-    inputs: RootParityInputs,
+    inputs: ParityRootPrivateInputs,
     signal?: AbortSignal,
     epochNumber?: number,
   ): Promise<PublicInputsAndRecursiveProof<ParityPublicInputs, typeof NESTED_RECURSIVE_PROOF_LENGTH>>;
 
+  getPublicChonkVerifierProof(
+    inputs: PublicChonkVerifierPrivateInputs,
+    signal?: AbortSignal,
+    epochNumber?: number,
+  ): Promise<
+    PublicInputsAndRecursiveProof<PublicChonkVerifierPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
+  >;
+
   /**
    * Creates a proof for the given input.
    * @param input - Input to the circuit.
    */
-  getPrivateBaseRollupProof(
-    baseRollupInput: PrivateBaseRollupInputs,
+  getPrivateTxBaseRollupProof(
+    baseRollupInput: PrivateTxBaseRollupPrivateInputs,
     signal?: AbortSignal,
     epochNumber?: number,
-  ): Promise<
-    PublicInputsAndRecursiveProof<BaseOrMergeRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
-  >;
+  ): Promise<PublicInputsAndRecursiveProof<TxRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>>;
 
-  getPublicBaseRollupProof(
-    inputs: PublicBaseRollupInputs,
+  getPublicTxBaseRollupProof(
+    inputs: PublicTxBaseRollupPrivateInputs,
     signal?: AbortSignal,
     epochNumber?: number,
-  ): Promise<
-    PublicInputsAndRecursiveProof<BaseOrMergeRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
-  >;
+  ): Promise<PublicInputsAndRecursiveProof<TxRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>>;
 
   /**
-   * Get a recursively verified client IVC proof (making it a compatible honk proof for the rest of the rollup).
+   * Creates a proof for the given input.
    * @param input - Input to the circuit.
    */
-  getTubeProof(
-    tubeInput: TubeInputs,
+  getTxMergeRollupProof(
+    input: TxMergeRollupPrivateInputs,
     signal?: AbortSignal,
     epochNumber?: number,
-  ): Promise<ProofAndVerificationKey<typeof TUBE_PROOF_LENGTH>>;
+  ): Promise<PublicInputsAndRecursiveProof<TxRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>>;
 
   /**
    * Creates a proof for the given input.
    * @param input - Input to the circuit.
    */
-  getMergeRollupProof(
-    input: MergeRollupInputs,
+  getBlockRootFirstRollupProof(
+    input: BlockRootFirstRollupPrivateInputs,
     signal?: AbortSignal,
     epochNumber?: number,
-  ): Promise<
-    PublicInputsAndRecursiveProof<BaseOrMergeRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
-  >;
+  ): Promise<PublicInputsAndRecursiveProof<BlockRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>>;
+
+  getBlockRootSingleTxFirstRollupProof(
+    input: BlockRootSingleTxFirstRollupPrivateInputs,
+    signal?: AbortSignal,
+    epochNumber?: number,
+  ): Promise<PublicInputsAndRecursiveProof<BlockRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>>;
+
+  getBlockRootEmptyTxFirstRollupProof(
+    input: BlockRootEmptyTxFirstRollupPrivateInputs,
+    signal?: AbortSignal,
+    epochNumber?: number,
+  ): Promise<PublicInputsAndRecursiveProof<BlockRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>>;
+
+  getBlockRootRollupProof(
+    input: BlockRootRollupPrivateInputs,
+    signal?: AbortSignal,
+    epochNumber?: number,
+  ): Promise<PublicInputsAndRecursiveProof<BlockRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>>;
+
+  getBlockRootSingleTxRollupProof(
+    input: BlockRootSingleTxRollupPrivateInputs,
+    signal?: AbortSignal,
+    epochNumber?: number,
+  ): Promise<PublicInputsAndRecursiveProof<BlockRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>>;
 
   /**
    * Creates a proof for the given input.
    * @param input - Input to the circuit.
    */
-  getBlockRootRollupProof(
-    input: BlockRootRollupInputs,
+  getBlockMergeRollupProof(
+    input: BlockMergeRollupPrivateInputs,
+    signal?: AbortSignal,
+    epochNumber?: number,
+  ): Promise<PublicInputsAndRecursiveProof<BlockRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>>;
+
+  getCheckpointRootRollupProof(
+    input: CheckpointRootRollupPrivateInputs,
     signal?: AbortSignal,
     epochNumber?: number,
   ): Promise<
-    PublicInputsAndRecursiveProof<BlockRootOrBlockMergePublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
+    PublicInputsAndRecursiveProof<CheckpointRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
   >;
 
-  getSingleTxBlockRootRollupProof(
-    input: SingleTxBlockRootRollupInputs,
+  getCheckpointRootSingleBlockRollupProof(
+    input: CheckpointRootSingleBlockRollupPrivateInputs,
     signal?: AbortSignal,
     epochNumber?: number,
   ): Promise<
-    PublicInputsAndRecursiveProof<BlockRootOrBlockMergePublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
+    PublicInputsAndRecursiveProof<CheckpointRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
   >;
 
-  /**
-   * Creates a proof for the given input.
-   * @param input - Input to the circuit.
-   */
-  getEmptyBlockRootRollupProof(
-    input: EmptyBlockRootRollupInputs,
+  getCheckpointPaddingRollupProof(
+    input: CheckpointPaddingRollupPrivateInputs,
     signal?: AbortSignal,
     epochNumber?: number,
   ): Promise<
-    PublicInputsAndRecursiveProof<BlockRootOrBlockMergePublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
+    PublicInputsAndRecursiveProof<CheckpointRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
   >;
 
-  /**
-   * Creates a proof for the given input.
-   * @param input - Input to the circuit.
-   */
-  getBlockMergeRollupProof(
-    input: BlockMergeRollupInputs,
+  getCheckpointMergeRollupProof(
+    input: CheckpointMergeRollupPrivateInputs,
     signal?: AbortSignal,
     epochNumber?: number,
   ): Promise<
-    PublicInputsAndRecursiveProof<BlockRootOrBlockMergePublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
+    PublicInputsAndRecursiveProof<CheckpointRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
   >;
 
   /**
@@ -138,7 +176,7 @@ export interface ServerCircuitProver {
    * @param input - Input to the circuit.
    */
   getRootRollupProof(
-    input: RootRollupInputs,
+    input: RootRollupPrivateInputs,
     signal?: AbortSignal,
     epochNumber?: number,
   ): Promise<PublicInputsAndRecursiveProof<RootRollupPublicInputs, typeof NESTED_RECURSIVE_PROOF_LENGTH>>;
@@ -151,9 +189,18 @@ export interface ServerCircuitProver {
     inputs: AvmCircuitInputs,
     signal?: AbortSignal,
     epochNumber?: number,
-  ): Promise<ProofAndVerificationKey<typeof AVM_PROOF_LENGTH_IN_FIELDS>>;
+  ): Promise<RecursiveProof<typeof AVM_V2_PROOF_LENGTH_IN_FIELDS_PADDED>>;
 }
 
+export type IVCProofVerificationResult = {
+  // The result of verification
+  valid: boolean;
+  // The duration of the verification in milliseconds
+  durationMs: number;
+  // The total duration, including proof serialisation and file-system cleanup
+  totalDurationMs: number;
+};
+
 /**
  * A verifier used by nodes to check tx proofs are valid.
  */
@@ -163,5 +210,10 @@ export interface ClientProtocolCircuitVerifier {
    * @param tx - The tx to verify the proof of
    * @returns True if the proof is valid, false otherwise
    */
-  verifyProof(tx: Tx): Promise<boolean>;
+  verifyProof(tx: Tx): Promise<IVCProofVerificationResult>;
+
+  /**
+   * Stop the verifier.
+   */
+  stop(): Promise<void>;
 }

package/src/interfaces/service.ts

@@ -1,5 +1,4 @@
 import type { Logger } from '@aztec/foundation/log';
-import type { Maybe } from '@aztec/foundation/types';
 
 /** Represents a local service that can be started and stopped. */
 export interface Service {
@@ -11,10 +10,13 @@ export interface Service {
 
   /** Stops the service. */
   stop(): Promise<void>;
+
+  /** Resumes the service after it was stopped */
+  resume(): void;
 }
 
 /** Tries to call stop on a given object and awaits it. Logs any errors and does not rethrow. */
-export async function tryStop(service: Maybe<Service>, logger?: Logger): Promise<void> {
+export async function tryStop(service?: any, logger?: Logger): Promise<void> {
   try {
     return typeof service === 'object' && service && 'stop' in service && typeof service.stop === 'function'
       ? await service.stop()

package/src/interfaces/slasher.ts

@@ -0,0 +1,52 @@
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import { schemas, zodFor } from '@aztec/foundation/schemas';
+
+import { z } from 'zod';
+
+export type SlasherClientType = 'empire' | 'tally';
+
+export interface SlasherConfig {
+  slashOverridePayload?: EthAddress;
+  slashMinPenaltyPercentage: number;
+  slashMaxPenaltyPercentage: number;
+  slashSelfAllowed?: boolean; // Whether to allow slashes to own validators
+  slashValidatorsAlways: EthAddress[]; // Array of validator addresses
+  slashValidatorsNever: EthAddress[]; // Array of validator addresses
+  slashInactivityTargetPercentage: number; // 0-1, 0.9 means 90%. Must be greater than 0
+  slashInactivityConsecutiveEpochThreshold: number; // Number of consecutive epochs a validator must be inactive before slashing
+  slashPrunePenalty: bigint;
+  slashDataWithholdingPenalty: bigint;
+  slashInactivityPenalty: bigint;
+  slashBroadcastedInvalidBlockPenalty: bigint;
+  slashProposeInvalidAttestationsPenalty: bigint;
+  slashAttestDescendantOfInvalidPenalty: bigint;
+  slashUnknownPenalty: bigint;
+  slashOffenseExpirationRounds: number; // Number of rounds after which pending offenses expire
+  slashMaxPayloadSize: number; // Maximum number of offenses to include in a single slash payload
+  slashGracePeriodL2Slots: number; // Number of L2 slots to wait after genesis before slashing for most offenses
+  slashExecuteRoundsLookBack: number; // How many rounds to look back when searching for a round to execute
+}
+
+export const SlasherConfigSchema = zodFor<SlasherConfig>()(
+  z.object({
+    slashOverridePayload: schemas.EthAddress.optional(),
+    slashMinPenaltyPercentage: z.number(),
+    slashMaxPenaltyPercentage: z.number(),
+    slashValidatorsAlways: z.array(schemas.EthAddress),
+    slashValidatorsNever: z.array(schemas.EthAddress),
+    slashPrunePenalty: schemas.BigInt,
+    slashDataWithholdingPenalty: schemas.BigInt,
+    slashInactivityTargetPercentage: z.number(),
+    slashInactivityConsecutiveEpochThreshold: z.number(),
+    slashInactivityPenalty: schemas.BigInt,
+    slashProposeInvalidAttestationsPenalty: schemas.BigInt,
+    slashAttestDescendantOfInvalidPenalty: schemas.BigInt,
+    slashUnknownPenalty: schemas.BigInt,
+    slashOffenseExpirationRounds: z.number(),
+    slashMaxPayloadSize: z.number(),
+    slashGracePeriodL2Slots: z.number(),
+    slashBroadcastedInvalidBlockPenalty: schemas.BigInt,
+    slashExecuteRoundsLookBack: z.number(),
+    slashSelfAllowed: z.boolean().optional(),
+  }),
+);

package/src/interfaces/tx_provider.ts

@@ -0,0 +1,17 @@
+import type { L2Block } from '@aztec/stdlib/block';
+import type { BlockProposal } from '@aztec/stdlib/p2p';
+import { type Tx, TxHash } from '@aztec/stdlib/tx';
+
+import type { PeerId } from '@libp2p/interface';
+
+export interface ITxProvider {
+  getAvailableTxs(txHashes: TxHash[]): Promise<{ txs: Tx[]; missingTxs: TxHash[] }>;
+
+  getTxsForBlockProposal(
+    blockProposal: BlockProposal,
+    blockNumber: number,
+    opts: { pinnedPeer: PeerId | undefined; deadline: Date },
+  ): Promise<{ txs: Tx[]; missingTxs: TxHash[] }>;
+
+  getTxsForBlock(block: L2Block, opts: { deadline: Date }): Promise<{ txs: Tx[]; missingTxs: TxHash[] }>;
+}

package/src/interfaces/validator.ts

@@ -0,0 +1,150 @@
+import type { BlockNumber, CheckpointNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import type { SecretValue } from '@aztec/foundation/config';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import type { Signature } from '@aztec/foundation/eth-signature';
+import { schemas, zodFor } from '@aztec/foundation/schemas';
+import type { SequencerConfig, SlasherConfig } from '@aztec/stdlib/interfaces/server';
+import type {
+  BlockProposal,
+  BlockProposalOptions,
+  CheckpointAttestation,
+  CheckpointLastBlockData,
+  CheckpointProposal,
+  CheckpointProposalOptions,
+} from '@aztec/stdlib/p2p';
+import type { CheckpointHeader } from '@aztec/stdlib/rollup';
+import type { BlockHeader, Tx } from '@aztec/stdlib/tx';
+import { type ValidatorHASignerConfig, ValidatorHASignerConfigSchema } from '@aztec/validator-ha-signer/config';
+
+import type { PeerId } from '@libp2p/interface';
+import { z } from 'zod';
+
+import type { CommitteeAttestationsAndSigners } from '../block/index.js';
+import { AllowedElementSchema } from './allowed_element.js';
+
+/**
+ * Validator client configuration
+ */
+export type ValidatorClientConfig = ValidatorHASignerConfig & {
+  /** The private keys of the validators participating in attestation duties */
+  validatorPrivateKeys?: SecretValue<`0x${string}`[]>;
+
+  /** The addresses of the validators to use with remote signers */
+  validatorAddresses?: EthAddress[];
+
+  /** Do not run the validator */
+  disableValidator: boolean;
+
+  /** Temporarily disable these specific validator addresses */
+  disabledValidators: EthAddress[];
+
+  /** Interval between polling for new attestations from peers */
+  attestationPollingIntervalMs: number;
+
+  /** Whether to re-execute transactions in a block proposal before attesting */
+  validatorReexecute: boolean;
+
+  /** Whether to always reexecute block proposals, even for non-validator nodes or when out of the currnet committee */
+  alwaysReexecuteBlockProposals?: boolean;
+
+  /** Whether to run in fisherman mode: validates all proposals and attestations but does not broadcast attestations or participate in consensus */
+  fishermanMode?: boolean;
+
+  /** Skip checkpoint proposal validation and always attest (default: false) */
+  skipCheckpointProposalValidation?: boolean;
+
+  /** Skip pushing re-executed blocks to archiver (default: false) */
+  skipPushProposedBlocksToArchiver?: boolean;
+};
+
+export type ValidatorClientFullConfig = ValidatorClientConfig &
+  Pick<SequencerConfig, 'txPublicSetupAllowList' | 'broadcastInvalidBlockProposal'> &
+  Pick<SlasherConfig, 'slashBroadcastedInvalidBlockPenalty'> & {
+    /**
+     * Whether transactions are disabled for this node
+     * @remarks This should match the property in P2PConfig. It's not picked from there to avoid circular dependencies.
+     */
+    disableTransactions?: boolean;
+  };
+
+export const ValidatorClientConfigSchema = zodFor<Omit<ValidatorClientConfig, 'validatorPrivateKeys'>>()(
+  ValidatorHASignerConfigSchema.extend({
+    validatorAddresses: z.array(schemas.EthAddress).optional(),
+    disableValidator: z.boolean(),
+    disabledValidators: z.array(schemas.EthAddress),
+    attestationPollingIntervalMs: z.number().min(0),
+    validatorReexecute: z.boolean(),
+    alwaysReexecuteBlockProposals: z.boolean().optional(),
+    fishermanMode: z.boolean().optional(),
+    skipCheckpointProposalValidation: z.boolean().optional(),
+    skipPushProposedBlocksToArchiver: z.boolean().optional(),
+  }),
+);
+
+export const ValidatorClientFullConfigSchema = zodFor<Omit<ValidatorClientFullConfig, 'validatorPrivateKeys'>>()(
+  ValidatorClientConfigSchema.extend({
+    txPublicSetupAllowList: z.array(AllowedElementSchema).optional(),
+    broadcastInvalidBlockProposal: z.boolean().optional(),
+    slashBroadcastedInvalidBlockPenalty: schemas.BigInt,
+    disableTransactions: z.boolean().optional(),
+  }),
+);
+
+export type CreateCheckpointProposalLastBlockData = Omit<CheckpointLastBlockData, 'txHashes'> & { txs: Tx[] };
+
+export interface Validator {
+  start(): Promise<void>;
+  updateConfig(config: Partial<ValidatorClientFullConfig>): void;
+
+  // Block validation responsibilities
+  createBlockProposal(
+    blockHeader: BlockHeader,
+    indexWithinCheckpoint: number,
+    inHash: Fr,
+    archive: Fr,
+    txs: Tx[],
+    proposerAddress: EthAddress | undefined,
+    options: BlockProposalOptions,
+  ): Promise<BlockProposal | undefined>;
+
+  /** Creates a checkpoint proposal for the last block in a checkpoint */
+  createCheckpointProposal(
+    checkpointHeader: CheckpointHeader,
+    archive: Fr,
+    lastBlockInfo: CreateCheckpointProposalLastBlockData | undefined,
+    proposerAddress: EthAddress | undefined,
+    options: CheckpointProposalOptions,
+  ): Promise<CheckpointProposal>;
+
+  /**
+   * Validate a block proposal from a peer.
+   * Note: Validators do NOT attest to individual blocks - attestations are only for checkpoint proposals.
+   * @returns true if the proposal is valid, false otherwise
+   */
+  validateBlockProposal(proposal: BlockProposal, sender: PeerId): Promise<boolean>;
+
+  /**
+   * Validate and attest to a checkpoint proposal from a peer.
+   * @returns Checkpoint attestations if valid, undefined otherwise
+   */
+  attestToCheckpointProposal(
+    proposal: CheckpointProposal,
+    sender: PeerId,
+  ): Promise<CheckpointAttestation[] | undefined>;
+
+  broadcastBlockProposal(proposal: BlockProposal): Promise<void>;
+
+  /** Collect own attestations for a checkpoint proposal (used when skipping p2p attestation collection) */
+  collectOwnAttestations(proposal: CheckpointProposal): Promise<CheckpointAttestation[]>;
+
+  /** Collect attestations from the p2p network for a checkpoint proposal */
+  collectAttestations(proposal: CheckpointProposal, required: number, deadline: Date): Promise<CheckpointAttestation[]>;
+
+  signAttestationsAndSigners(
+    attestationsAndSigners: CommitteeAttestationsAndSigners,
+    proposer: EthAddress,
+    slot: SlotNumber,
+    blockNumber: BlockNumber | CheckpointNumber,
+  ): Promise<Signature>;
+}

package/src/interfaces/world_state.ts

@@ -1,7 +1,13 @@
+import { BlockNumber, BlockNumberSchema } from '@aztec/foundation/branded-types';
+import type { PromiseWithResolvers } from '@aztec/foundation/promise';
+
 import { z } from 'zod';
 
+import type { SnapshotDataKeys } from '../snapshots/types.js';
 import type { MerkleTreeReadOperations, MerkleTreeWriteOperations } from './merkle_tree_operations.js';
 
+export type { SnapshotDataKeys };
+
 /**
  * Defines the possible states of the world state synchronizer.
  */
@@ -13,10 +19,10 @@ export enum WorldStateRunningState {
 }
 
 export interface WorldStateSyncStatus {
-  latestBlockNumber: number;
+  latestBlockNumber: BlockNumber;
   latestBlockHash: string;
-  finalisedBlockNumber: number;
-  oldestHistoricBlockNumber: number;
+  finalizedBlockNumber: BlockNumber;
+  oldestHistoricBlockNumber: BlockNumber;
   treesAreSynched: boolean;
 }
 
@@ -36,49 +42,59 @@ export interface WorldStateSynchronizerStatus {
 
 /** Provides writeable forks of the world state at a given block number. */
 export interface ForkMerkleTreeOperations {
-  /** Forks the world state at the given block number, defaulting to the latest one. */
-  fork(block?: number): Promise<MerkleTreeWriteOperations>;
+  /**
+   * Forks the world state at the given block number, defaulting to the latest one.
+   * @param block - The block number to fork at.
+   * @param opts - Optional parameters:
+   *  - closeDelayMs: number of milliseconds to wait before closing the fork on dispose.
+   */
+  fork(block?: BlockNumber, opts?: { closeDelayMs?: number }): Promise<MerkleTreeWriteOperations>;
+
+  /** Backups the db to the target path. */
+  backupTo(dstPath: string, compact?: boolean): Promise<Record<Exclude<SnapshotDataKeys, 'archiver'>, string>>;
+}
+
+export interface ReadonlyWorldStateAccess {
+  /** Returns an instance of MerkleTreeAdminOperations that will not include uncommitted data. */
+  getCommitted(): MerkleTreeReadOperations;
 
   /** Gets a handle that allows reading the state as it was at the given block number. */
   getSnapshot(blockNumber: number): MerkleTreeReadOperations;
 }
 
 /** Defines the interface for a world state synchronizer. */
-export interface WorldStateSynchronizer extends ForkMerkleTreeOperations {
-  /**
-   * Starts the synchronizer.
-   * @returns A promise that resolves once the initial sync is completed.
-   */
-  start(): void;
+export interface WorldStateSynchronizer extends ReadonlyWorldStateAccess, ForkMerkleTreeOperations {
+  /** Starts the synchronizer. */
+  start(): Promise<void | PromiseWithResolvers<void>>;
 
-  /**
-   * Returns the current status of the synchronizer.
-   * @returns The current status of the synchronizer.
-   */
+  /** Returns the current status of the synchronizer. */
   status(): Promise<WorldStateSynchronizerStatus>;
 
-  /**
-   * Stops the synchronizer.
-   */
+  /** Stops the synchronizer and its database. */
   stop(): Promise<void>;
 
+  /** Stops the synchronizer from syncing, but keeps the database online. */
+  stopSync(): Promise<void>;
+
+  /** Resumes synching after a stopSync call. */
+  resumeSync(): void;
+
   /**
    * Forces an immediate sync to an optionally provided minimum block number
-   * @param minBlockNumber - The minimum block number that we must sync to
+   * @param targetBlockNumber - The target block number that we must sync to. Will download unproven blocks if needed to reach it.
+   * @param skipThrowIfTargetNotReached - Whether to skip throwing if the target block number is not reached.
    * @returns A promise that resolves with the block number the world state was synced to
    */
-  syncImmediate(minBlockNumber?: number): Promise<number>;
+  syncImmediate(minBlockNumber?: BlockNumber, skipThrowIfTargetNotReached?: boolean): Promise<BlockNumber>;
 
-  /**
-   * Returns an instance of MerkleTreeAdminOperations that will not include uncommitted data.
-   */
-  getCommitted(): MerkleTreeReadOperations;
+  /** Deletes the db */
+  clear(): Promise<void>;
 }
 
-export const WorldStateSyncStatusSchema = z.object({
-  finalisedBlockNumber: z.number().int().nonnegative(),
-  latestBlockNumber: z.number().int().nonnegative(),
+export const WorldStateSyncStatusSchema: z.ZodType<WorldStateSyncStatus, z.ZodTypeDef, any> = z.object({
+  finalizedBlockNumber: BlockNumberSchema,
+  latestBlockNumber: BlockNumberSchema,
   latestBlockHash: z.string(),
-  oldestHistoricBlockNumber: z.number().int().nonnegative(),
+  oldestHistoricBlockNumber: BlockNumberSchema,
   treesAreSynched: z.boolean(),
-}) satisfies z.ZodType<WorldStateSyncStatus>;
+});