@aztec/stdlib 0.0.1-commit.e6bd8901 → 0.0.1-commit.ec7ac5448

package/src/abi/function_signature_decoder.ts

@@ -0,0 +1,77 @@
+import type { ABIParameter, ABIVariable, AbiType } from './abi.js';
+
+/**
+ * Decodes the signature of a function from the name and parameters.
+ */
+export class FunctionSignatureDecoder {
+  private separator: string;
+  constructor(
+    private name: string,
+    private parameters: ABIParameter[],
+    private includeNames = false,
+  ) {
+    this.separator = includeNames ? ', ' : ',';
+  }
+
+  /**
+   * Decodes a single function parameter type for the function signature.
+   * @param param - The parameter type to decode.
+   * @returns A string representing the parameter type.
+   */
+  private getParameterType(param: AbiType): string {
+    switch (param.kind) {
+      case 'field':
+        return 'Field';
+      case 'integer':
+        return param.sign === 'signed' ? `i${param.width}` : `u${param.width}`;
+      case 'boolean':
+        return 'bool';
+      case 'array':
+        return `[${this.getParameterType(param.type)};${param.length}]`;
+      case 'string':
+        return `str<${param.length}>`;
+      case 'struct':
+        return `(${param.fields.map(field => `${this.decodeParameter(field)}`).join(this.separator)})`;
+      default:
+        throw new Error(`Unsupported type: ${param.kind}`);
+    }
+  }
+
+  /**
+   * Decodes a single function parameter for the function signature.
+   * @param param - The parameter to decode.
+   * @returns A string representing the parameter type and optionally its name.
+   */
+  private decodeParameter(param: ABIVariable): string {
+    const type = this.getParameterType(param.type);
+    return this.includeNames ? `${param.name}: ${type}` : type;
+  }
+
+  /**
+   * Decodes all the parameters and build the function signature
+   * @returns The function signature.
+   */
+  public decode(): string {
+    return `${this.name}(${this.parameters.map(param => this.decodeParameter(param)).join(this.separator)})`;
+  }
+}
+
+/**
+ * Decodes a function signature from the name and parameters.
+ * @param name - The name of the function.
+ * @param parameters - The parameters of the function.
+ * @returns - The function signature.
+ */
+export function decodeFunctionSignature(name: string, parameters: ABIParameter[]) {
+  return new FunctionSignatureDecoder(name, parameters).decode();
+}
+
+/**
+ * Decodes a function signature from the name and parameters including parameter names.
+ * @param name - The name of the function.
+ * @param parameters - The parameters of the function.
+ * @returns - The user-friendly function signature.
+ */
+export function decodeFunctionSignatureWithParameterNames(name: string, parameters: ABIParameter[]) {
+  return new FunctionSignatureDecoder(name, parameters, true).decode();
+}

package/src/abi/index.ts

@@ -1,6 +1,7 @@
 export * from './abi.js';
 export * from './buffer.js';
 export * from './decoder.js';
+export * from './function_signature_decoder.js';
 export * from './encoder.js';
 export * from './authorization_selector.js';
 export * from './event_metadata_definition.js';

package/src/abi/selector.ts

@@ -4,7 +4,7 @@ import { bufferToHex } from '@aztec/foundation/string';
 
 import { inspect } from 'util';
 
-/** A selector is the first 4 bytes of the hash of a signature. */
+/** A selector is the low 4 bytes of the poseidon2 hash of a signature. */
 export abstract class Selector {
   /** The size of the selector in bytes. */
   public static SIZE = 4;

package/src/abi/utils.ts

@@ -81,6 +81,31 @@ export function isBoundedVecStruct(abiType: AbiType) {
   );
 }
 
+/**
+ * Returns whether the ABI type is Noir's std::option::Option lowered to a struct.
+ * @param abiType - Type to check.
+ * @returns A boolean indicating whether the ABI type is an Option struct.
+ */
+export function isOptionStruct(abiType: AbiType) {
+  return (
+    abiType.kind === 'struct' &&
+    abiType.path === 'std::option::Option' &&
+    abiType.fields.length === 2 &&
+    abiType.fields[0].name === '_is_some' &&
+    abiType.fields[1].name === '_value'
+  );
+}
+
+/**
+ * Returns whether `null` or `undefined` can be mapped to a valid ABI value for this type.
+ *
+ * @param abiType - Type to check.
+ * @returns A boolean indicating whether nullish values are valid shorthand for this ABI type.
+ */
+export function canBeMappedFromNullOrUndefined(abiType: AbiType) {
+  return isOptionStruct(abiType);
+}
+
 /**
  * Returns a bigint by parsing a serialized 2's complement signed int.
  * @param b - The signed int as a buffer

package/src/auth_witness/auth_witness.ts

@@ -1,4 +1,4 @@
-import { GeneratorIndex } from '@aztec/constants';
+import { DomainSeparator } from '@aztec/constants';
 import { poseidon2HashWithSeparator } from '@aztec/foundation/crypto/poseidon';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
@@ -61,7 +61,7 @@ export class AuthWitness {
  * @returns The inner hash for the witness
  */
 export const computeInnerAuthWitHash = (args: Fr[]) => {
-  return poseidon2HashWithSeparator(args, GeneratorIndex.AUTHWIT_INNER);
+  return poseidon2HashWithSeparator(args, DomainSeparator.AUTHWIT_INNER);
 };
 
 /**
@@ -77,5 +77,5 @@ export const computeInnerAuthWitHash = (args: Fr[]) => {
  * @returns The outer hash for the witness
  */
 export const computeOuterAuthWitHash = (consumer: AztecAddress, chainId: Fr, version: Fr, innerHash: Fr) => {
-  return poseidon2HashWithSeparator([consumer.toField(), chainId, version, innerHash], GeneratorIndex.AUTHWIT_OUTER);
+  return poseidon2HashWithSeparator([consumer.toField(), chainId, version, innerHash], DomainSeparator.AUTHWIT_OUTER);
 };

package/src/avm/revert_code.ts

@@ -5,20 +5,17 @@ import { BufferReader, FieldReader } from '@aztec/foundation/serialize';
 import { inspect } from 'util';
 import { z } from 'zod';
 
+/** Whether a transaction's public execution reverted. */
 export enum RevertCodeEnum {
+  /** All phases completed successfully; no state was rolled back. */
   OK = 0,
-  APP_LOGIC_REVERTED = 1,
-  TEARDOWN_REVERTED = 2,
-  BOTH_REVERTED = 3,
+  /** One or more revertible phases reverted; their state changes were discarded. */
+  REVERTED = 1,
 }
 
-function isRevertCodeEnum(value: number): value is RevertCodeEnum {
-  return (
-    (value as RevertCodeEnum) === RevertCodeEnum.OK ||
-    (value as RevertCodeEnum) === RevertCodeEnum.APP_LOGIC_REVERTED ||
-    (value as RevertCodeEnum) === RevertCodeEnum.TEARDOWN_REVERTED ||
-    (value as RevertCodeEnum) === RevertCodeEnum.BOTH_REVERTED
-  );
+/** Returns a valid RevertCodeEnum, coercing any value >= 1 to REVERTED. */
+function toRevertCodeEnum(value: number): RevertCodeEnum {
+  return value >= 1 ? RevertCodeEnum.REVERTED : RevertCodeEnum.OK;
 }
 
 /**
@@ -30,9 +27,13 @@ export class RevertCode {
     this.code = e.valueOf();
   }
   static readonly OK: RevertCode = new RevertCode(RevertCodeEnum.OK);
-  static readonly APP_LOGIC_REVERTED: RevertCode = new RevertCode(RevertCodeEnum.APP_LOGIC_REVERTED);
-  static readonly TEARDOWN_REVERTED: RevertCode = new RevertCode(RevertCodeEnum.TEARDOWN_REVERTED);
-  static readonly BOTH_REVERTED: RevertCode = new RevertCode(RevertCodeEnum.BOTH_REVERTED);
+  static readonly REVERTED: RevertCode = new RevertCode(RevertCodeEnum.REVERTED);
+  /** @deprecated Use REVERTED instead. */
+  static readonly APP_LOGIC_REVERTED: RevertCode = RevertCode.REVERTED;
+  /** @deprecated Use REVERTED instead. */
+  static readonly TEARDOWN_REVERTED: RevertCode = RevertCode.REVERTED;
+  /** @deprecated Use REVERTED instead. */
+  static readonly BOTH_REVERTED: RevertCode = RevertCode.REVERTED;
 
   public getCode(): RevertCodeEnum {
     return this.code;
@@ -50,12 +51,8 @@ export class RevertCode {
     switch (this.code as RevertCodeEnum) {
       case RevertCodeEnum.OK:
         return 'OK';
-      case RevertCodeEnum.APP_LOGIC_REVERTED:
-        return 'Application logic reverted';
-      case RevertCodeEnum.TEARDOWN_REVERTED:
-        return 'Teardown reverted';
-      case RevertCodeEnum.BOTH_REVERTED:
-        return 'Both reverted';
+      case RevertCodeEnum.REVERTED:
+        return 'Reverted';
       default:
         return `Unknown RevertCode: ${this.code}`;
     }
@@ -66,7 +63,11 @@ export class RevertCode {
   }
 
   static get schema(): ZodFor<RevertCode> {
-    return z.nativeEnum(RevertCodeEnum).transform(value => new RevertCode(value));
+    return z
+      .number()
+      .int()
+      .min(0)
+      .transform(value => new RevertCode(toRevertCodeEnum(value)));
   }
 
   /**
@@ -81,10 +82,10 @@ export class RevertCode {
       return obj;
     }
     const code = typeof obj === 'number' ? obj : (obj.code ?? obj);
-    if (!isRevertCodeEnum(code)) {
+    if (typeof code !== 'number' || code < 0) {
       throw new Error(`Invalid RevertCode: ${code}`);
     }
-    return new RevertCode(code);
+    return new RevertCode(toRevertCodeEnum(code));
   }
 
   /**
@@ -116,10 +117,10 @@ export class RevertCode {
   }
 
   public static fromNumber(code: number): RevertCode {
-    if (!isRevertCodeEnum(code)) {
+    if (code < 0) {
       throw new Error(`Invalid RevertCode: ${code}`);
     }
-    return new RevertCode(code);
+    return new RevertCode(toRevertCodeEnum(code));
   }
 
   public static fromField(field: Fr): RevertCode {
@@ -137,7 +138,7 @@ export class RevertCode {
     return RevertCode.fromNumber(code);
   }
 
-  private static readonly NUM_OPTIONS = 4;
+  private static readonly NUM_OPTIONS = 2;
   static random(): RevertCode {
     return new RevertCode(Math.floor(Math.random() * RevertCode.NUM_OPTIONS));
   }

package/src/block/block_data.ts

@@ -0,0 +1,26 @@
+import { CheckpointNumberSchema, IndexWithinCheckpointSchema } from '@aztec/foundation/branded-types';
+import type { CheckpointNumber, IndexWithinCheckpoint } from '@aztec/foundation/branded-types';
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import { schemas } from '@aztec/foundation/schemas';
+
+import { z } from 'zod';
+
+import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
+import { BlockHeader } from '../tx/block_header.js';
+
+/** L2Block metadata. Equivalent to L2Block but without block body containing tx data. */
+export type BlockData = {
+  header: BlockHeader;
+  archive: AppendOnlyTreeSnapshot;
+  blockHash: Fr;
+  checkpointNumber: CheckpointNumber;
+  indexWithinCheckpoint: IndexWithinCheckpoint;
+};
+
+export const BlockDataSchema = z.object({
+  header: BlockHeader.schema,
+  archive: AppendOnlyTreeSnapshot.schema,
+  blockHash: schemas.Fr,
+  checkpointNumber: CheckpointNumberSchema,
+  indexWithinCheckpoint: IndexWithinCheckpointSchema,
+});

package/src/block/block_hash.ts

@@ -1,66 +1,45 @@
-import { Buffer32 } from '@aztec/foundation/buffer';
 import { Fr } from '@aztec/foundation/curves/bn254';
-import { BufferReader } from '@aztec/foundation/serialize';
+import type { ZodFor } from '@aztec/foundation/schemas';
 
-import { schemas } from '../schemas/schemas.js';
+import { inspect } from 'util';
 
-/** Hash of an L2 block. */
-export class L2BlockHash extends Buffer32 {
-  constructor(
-    /** The buffer containing the hash. */
-    hash: Buffer,
-  ) {
-    super(hash);
-  }
+import { hexSchemaFor } from '../schemas/schemas.js';
 
-  /**
-   * Type guard that checks if a value is an L2BlockHash instance.
-   * Uses duck typing to handle cases where instanceof fails due to module duplication.
-   * Checks for Buffer32-like structure with a 32-byte buffer.
-   */
-  static isL2BlockHash(value: unknown): value is L2BlockHash {
-    if (value instanceof L2BlockHash) {
-      return true;
-    }
-    // Duck typing fallback: check if it looks like a Buffer32 with a 32-byte buffer
-    // This helps when instanceof fails due to module duplication
-    return (
-      typeof value === 'object' &&
-      value !== null &&
-      'buffer' in value &&
-      Buffer.isBuffer((value as Buffer32).buffer) &&
-      (value as Buffer32).buffer.length === 32 &&
-      'toBuffer' in value &&
-      typeof (value as Buffer32).toBuffer === 'function'
-    );
-  }
+const BLOCK_HASH_BRAND = Symbol.for('aztec.BlockHash');
 
-  static override random() {
-    return new L2BlockHash(Fr.random().toBuffer());
+/** Hash of an L2 block. */
+export class BlockHash extends Fr {
+  readonly [BLOCK_HASH_BRAND] = true as const;
+
+  constructor(hash: Fr) {
+    super(hash);
   }
 
-  static override fromNumber(num: number): L2BlockHash {
-    return new L2BlockHash(super.fromNumber(num).toBuffer());
+  override [inspect.custom]() {
+    return `BlockHash<${this.toString()}>`;
   }
 
-  static override fromBuffer(buffer: Buffer | BufferReader) {
-    const reader = BufferReader.asReader(buffer);
-    return new L2BlockHash(reader.readBytes(L2BlockHash.SIZE));
+  toFr(): Fr {
+    return new Fr(this.toBigInt());
   }
 
-  static override fromString(str: string): Buffer32 {
-    return new L2BlockHash(super.fromString(str).toBuffer());
+  /**
+   * Type guard that checks if a value is a BlockHash instance.
+   * Uses Symbol.for to ensure cross-module compatibility.
+   */
+  static isBlockHash(value: unknown): value is BlockHash {
+    return typeof value === 'object' && value !== null && BLOCK_HASH_BRAND in value;
   }
 
-  static get schema() {
-    return schemas.BufferHex.transform(value => new L2BlockHash(value));
+  static override random() {
+    return new BlockHash(Fr.random());
   }
 
-  static zero() {
-    return new L2BlockHash(Buffer32.ZERO.toBuffer());
+  static override fromString(str: string): BlockHash {
+    return new BlockHash(Fr.fromString(str));
   }
 
-  static override fromField(hash: Fr) {
-    return new L2BlockHash(hash.toBuffer());
+  static override get schema() {
+    return hexSchemaFor(BlockHash) as ZodFor<BlockHash>;
   }
 }

package/src/block/block_parameter.ts

@@ -2,9 +2,9 @@ import { BlockNumberSchema } from '@aztec/foundation/branded-types';
 
 import { z } from 'zod';
 
-import { L2BlockHash } from './block_hash.js';
+import { BlockHash } from './block_hash.js';
 
-export const BlockParameterSchema = z.union([L2BlockHash.schema, BlockNumberSchema, z.literal('latest')]);
+export const BlockParameterSchema = z.union([BlockHash.schema, BlockNumberSchema, z.literal('latest')]);
 
-/** Block parameter - either a specific BlockNumber, block hash (L2BlockHash), or 'latest' */
+/** Block parameter - either a specific BlockNumber, block hash (BlockHash), or 'latest' */
 export type BlockParameter = z.infer<typeof BlockParameterSchema>;

package/src/block/in_block.ts

@@ -2,12 +2,12 @@ import { BlockNumber, BlockNumberSchema } from '@aztec/foundation/branded-types'
 
 import { type ZodTypeAny, z } from 'zod';
 
-import { L2BlockHash } from './block_hash.js';
+import { BlockHash } from './block_hash.js';
 import type { L2Block } from './l2_block.js';
 
 export type InBlock = {
   l2BlockNumber: BlockNumber;
-  l2BlockHash: L2BlockHash;
+  l2BlockHash: BlockHash;
 };
 
 // Note: If you expand this type with indexInBlock, then delete `IndexedTxEffect` and use this type instead.
@@ -17,8 +17,8 @@ export type DataInBlock<T> = {
 
 export function randomInBlock(): InBlock {
   return {
-    l2BlockNumber: BlockNumber(Math.floor(Math.random() * 1000)),
-    l2BlockHash: L2BlockHash.random(),
+    l2BlockNumber: BlockNumber(Math.floor(Math.random() * 1000) + 1),
+    l2BlockHash: BlockHash.random(),
   };
 }
 
@@ -33,14 +33,14 @@ export async function wrapDataInBlock<T>(data: T, block: L2Block): Promise<DataI
   return {
     data,
     l2BlockNumber: block.number,
-    l2BlockHash: L2BlockHash.fromField(await block.hash()),
+    l2BlockHash: await block.hash(),
   };
 }
 
 export function inBlockSchema() {
   return z.object({
     l2BlockNumber: BlockNumberSchema,
-    l2BlockHash: L2BlockHash.schema,
+    l2BlockHash: BlockHash.schema,
   });
 }
 

package/src/block/index.ts

@@ -1,3 +1,4 @@
+export * from './block_data.js';
 export * from './l2_block.js';
 export * from './l2_block_stream/index.js';
 export * from './in_block.js';

package/src/block/l2_block.ts

@@ -1,4 +1,5 @@
 import { type BlockBlobData, encodeBlockBlobData } from '@aztec/blob-lib/encoding';
+import { DA_GAS_PER_FIELD } from '@aztec/constants';
 import {
   BlockNumber,
   CheckpointNumber,
@@ -15,6 +16,7 @@ import { z } from 'zod';
 import type { PrivateLog } from '../logs/private_log.js';
 import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
 import { BlockHeader } from '../tx/block_header.js';
+import type { BlockHash } from './block_hash.js';
 import { Body } from './body.js';
 import type { L2BlockInfo } from './l2_block_info.js';
 
@@ -89,7 +91,7 @@ export class L2Block {
    * Returns the block's hash (hash of block header).
    * @returns The block's hash.
    */
-  public hash(): Promise<Fr> {
+  public hash(): Promise<BlockHash> {
     return this.header.hash();
   }
 
@@ -174,7 +176,7 @@ export class L2Block {
     } & Partial<Parameters<typeof BlockHeader.random>[0]> = {},
   ): Promise<L2Block> {
     const archive = new AppendOnlyTreeSnapshot(Fr.random(), blockNumber + 1);
-    const header = BlockHeader.random({ blockNumber, ...blockHeaderOverrides });
+    const header = BlockHeader.random({ ...blockHeaderOverrides, blockNumber });
     const body = await Body.random({ txsPerBlock, makeTxOptions, ...txOptions });
     return new L2Block(archive, header, body, checkpointNumber, indexWithinCheckpoint);
   }
@@ -220,4 +222,15 @@ export class L2Block {
       timestamp: this.header.globalVariables.timestamp,
     };
   }
+
+  /**
+   * Compute how much DA gas this block uses.
+   *
+   * @remarks This assumes DA gas is computed solely based on the number of blob fields in transactions.
+   * This may change in the future, but we cannot access the actual DA gas used in a block since it's not exposed
+   * in the L2BlockHeader, so we have to rely on recomputing it.
+   */
+  computeDAGasUsed(): number {
+    return this.body.txEffects.reduce((total, txEffect) => total + txEffect.getNumBlobFields(), 0) * DA_GAS_PER_FIELD;
+  }
 }

package/src/block/l2_block_source.ts

@@ -13,6 +13,7 @@ import type { TypedEventEmitter } from '@aztec/foundation/types';
 import { z } from 'zod';
 
 import type { Checkpoint } from '../checkpoint/checkpoint.js';
+import type { CheckpointData, CommonCheckpointData, ProposedCheckpointData } from '../checkpoint/checkpoint_data.js';
 import type { PublishedCheckpoint } from '../checkpoint/published_checkpoint.js';
 import type { L1RollupConstants } from '../epoch-helpers/index.js';
 import { CheckpointHeader } from '../rollup/checkpoint_header.js';
@@ -20,6 +21,8 @@ import type { BlockHeader } from '../tx/block_header.js';
 import type { IndexedTxEffect } from '../tx/indexed_tx_effect.js';
 import type { TxHash } from '../tx/tx_hash.js';
 import type { TxReceipt } from '../tx/tx_receipt.js';
+import type { BlockData } from './block_data.js';
+import type { BlockHash } from './block_hash.js';
 import type { CheckpointedL2Block } from './checkpointed_l2_block.js';
 import type { L2Block } from './l2_block.js';
 import type { ValidateCheckpointNegativeResult, ValidateCheckpointResult } from './validate_block_result.js';
@@ -46,6 +49,12 @@ export interface L2BlockSource {
    */
   getBlockNumber(): Promise<BlockNumber>;
 
+  /**
+   * Gets the number of the latest L2 checkpoint processed by the block source implementation.
+   * @returns The number of the latest L2 checkpoint processed by the block source implementation.
+   */
+  getCheckpointNumber(): Promise<CheckpointNumber>;
+
   /**
    * Gets the number of the latest L2 block proven seen by the block source implementation.
    * @returns The number of the latest L2 block proven seen by the block source implementation.
@@ -59,9 +68,8 @@ export interface L2BlockSource {
   getCheckpointedL2BlockNumber(): Promise<BlockNumber>;
 
   /**
-   * Computes the finalized block number based on the proven block number.
-   * A block is considered finalized when it's 2 epochs behind the proven block.
-   * TODO(#13569): Compute proper finalized block number based on L1 finalized block.
+   * Returns the finalized L2 block number. A block is finalized when it was proven
+   * in an L1 block that has itself been finalized on Ethereum.
    * @returns The finalized block number.
    */
   getFinalizedL2BlockNumber(): Promise<BlockNumber>;
@@ -97,12 +105,18 @@ export interface L2BlockSource {
    */
   getCheckpointsForEpoch(epochNumber: EpochNumber): Promise<Checkpoint[]>;
 
+  /**
+   * Gets lightweight checkpoint metadata for a given epoch, without fetching full block data.
+   * @param epochNumber - Epoch for which we want checkpoint data
+   */
+  getCheckpointsDataForEpoch(epochNumber: EpochNumber): Promise<CheckpointData[]>;
+
   /**
    * Gets a block header by its hash.
    * @param blockHash - The block hash to retrieve.
    * @returns The requested block header (or undefined if not found).
    */
-  getBlockHeaderByHash(blockHash: Fr): Promise<BlockHeader | undefined>;
+  getBlockHeaderByHash(blockHash: BlockHash): Promise<BlockHeader | undefined>;
 
   /**
    * Gets a block header by its archive root.
@@ -111,6 +125,20 @@ export interface L2BlockSource {
    */
   getBlockHeaderByArchive(archive: Fr): Promise<BlockHeader | undefined>;
 
+  /**
+   * Gets block metadata (without tx data) by block number.
+   * @param number - The block number to retrieve.
+   * @returns The requested block data (or undefined if not found).
+   */
+  getBlockData(number: BlockNumber): Promise<BlockData | undefined>;
+
+  /**
+   * Gets block metadata (without tx data) by archive root.
+   * @param archive - The archive root to retrieve.
+   * @returns The requested block data (or undefined if not found).
+   */
+  getBlockDataByArchive(archive: Fr): Promise<BlockData | undefined>;
+
   /**
    * Gets an L2 block by block number.
    * @param number - The block number to return.
@@ -123,7 +151,7 @@ export interface L2BlockSource {
    * @param blockHash - The block hash to retrieve.
    * @returns The requested L2 block (or undefined if not found).
    */
-  getL2BlockByHash(blockHash: Fr): Promise<L2Block | undefined>;
+  getL2BlockByHash(blockHash: BlockHash): Promise<L2Block | undefined>;
 
   /**
    * Gets an L2 block by its archive root.
@@ -147,14 +175,18 @@ export interface L2BlockSource {
   getSettledTxReceipt(txHash: TxHash): Promise<TxReceipt | undefined>;
 
   /**
-   * Returns the current L2 slot number based on the currently synced L1 timestamp.
+   * Returns the last L2 slot number for which we have all L1 data needed to build the next checkpoint.
+   * Determined by the max of two signals: L1 block sync progress and latest synced checkpoint slot.
+   * The checkpoint signal handles missed L1 blocks, since a published checkpoint seals the message tree
+   * for the next checkpoint via the inbox LAG mechanism.
    */
-  getL2SlotNumber(): Promise<SlotNumber | undefined>;
+  getSyncedL2SlotNumber(): Promise<SlotNumber | undefined>;
 
   /**
-   * Returns the current L2 epoch number based on the currently synced L1 timestamp.
+   * Returns the last L2 epoch number that has been fully synchronized from L1.
+   * An epoch is fully synced when all its L2 slots have been fully synced.
    */
-  getL2EpochNumber(): Promise<EpochNumber | undefined>;
+  getSyncedL2EpochNumber(): Promise<EpochNumber | undefined>;
 
   /**
    * Returns all checkpointed block headers for a given epoch.
@@ -197,6 +229,12 @@ export interface L2BlockSource {
    */
   getPendingChainValidationStatus(): Promise<ValidateCheckpointResult>;
 
+  /** Returns the checkpoint at the proposed chain tip. */
+  getProposedCheckpoint(): Promise<CommonCheckpointData | undefined>;
+
+  /** Returns proposed checkpoint, if set, undefined if not*/
+  getProposedCheckpointOnly(): Promise<ProposedCheckpointData | undefined>;
+
   /** Force a sync. */
   syncImmediate(): Promise<void>;
 
@@ -228,7 +266,7 @@ export interface L2BlockSource {
    * @param blockHash - The block hash to retrieve.
    * @returns The requested block (or undefined if not found).
    */
-  getCheckpointedBlockByHash(blockHash: Fr): Promise<CheckpointedL2Block | undefined>;
+  getCheckpointedBlockByHash(blockHash: BlockHash): Promise<CheckpointedL2Block | undefined>;
 
   /**
    * Gets a checkpointed block by its archive root.
@@ -280,12 +318,13 @@ export interface L2BlockSourceEventEmitter extends L2BlockSource {
  * - proven: Proven block on L1.
  * - finalized: Proven block on a finalized L1 block (not implemented, set to proven for now).
  */
-export type L2BlockTag = 'proposed' | 'checkpointed' | 'proven' | 'finalized';
+export type L2BlockTag = 'proposed' | 'proposedCheckpoint' | 'checkpointed' | 'proven' | 'finalized';
 
 /** Tips of the L2 chain. */
 export type L2Tips = {
   proposed: L2BlockId;
   checkpointed: L2TipId;
+  proposedCheckpoint: L2TipId;
   proven: L2TipId;
   finalized: L2TipId;
 };
@@ -330,6 +369,7 @@ const L2TipIdSchema = z.object({
 export const L2TipsSchema = z.object({
   proposed: L2BlockIdSchema,
   checkpointed: L2TipIdSchema,
+  proposedCheckpoint: L2TipIdSchema,
   proven: L2TipIdSchema,
   finalized: L2TipIdSchema,
 });