@aztec/stdlib 0.0.0-test.1 → 0.0.1-commit.b655e406

package/src/block/l2_block_header.ts

@@ -0,0 +1,232 @@
+import { Fr } from '@aztec/foundation/fields';
+import { type ZodFor, schemas } from '@aztec/foundation/schemas';
+import { BufferReader, FieldReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
+import { bufferToHex, hexToBuffer } from '@aztec/foundation/string';
+import type { FieldsOf } from '@aztec/foundation/types';
+
+import { inspect } from 'util';
+import { z } from 'zod';
+
+import { CheckpointHeader } from '../rollup/checkpoint_header.js';
+import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
+import { BlockHeader, ContentCommitment, GlobalVariables, StateReference } from '../tx/index.js';
+
+/**
+ * TO BE DELETED
+ *
+ * A header of an L2 block combining the block header and the checkpoint header.
+ * This is a temporary workaround to avoid changing too many things before building in chunks is properly implemented.
+ * This works for now because we only have one block per checkpoint.
+ *
+ * @deprecated Use BlockHeader or CheckpointHeader instead.
+ */
+export class L2BlockHeader {
+  constructor(
+    /** Snapshot of archive before the block is applied. */
+    public lastArchive: AppendOnlyTreeSnapshot,
+    /** Hash of the body of an L2 block. */
+    public contentCommitment: ContentCommitment,
+    /** State reference. */
+    public state: StateReference,
+    /** Global variables of an L2 block. */
+    public globalVariables: GlobalVariables,
+    /** Total fees in the block, computed by the root rollup circuit */
+    public totalFees: Fr,
+    /** Total mana used in the block, computed by the root rollup circuit */
+    public totalManaUsed: Fr,
+    /** Hash of the sponge blob of the block. */
+    public spongeBlobHash: Fr,
+  ) {}
+
+  static get schema(): ZodFor<L2BlockHeader> {
+    return z
+      .object({
+        lastArchive: AppendOnlyTreeSnapshot.schema,
+        contentCommitment: ContentCommitment.schema,
+        state: StateReference.schema,
+        globalVariables: GlobalVariables.schema,
+        totalFees: schemas.Fr,
+        totalManaUsed: schemas.Fr,
+        spongeBlobHash: schemas.Fr,
+      })
+      .transform(L2BlockHeader.from);
+  }
+
+  static getFields(fields: FieldsOf<L2BlockHeader>) {
+    return [
+      fields.lastArchive,
+      fields.contentCommitment,
+      fields.state,
+      fields.globalVariables,
+      fields.totalFees,
+      fields.totalManaUsed,
+      fields.spongeBlobHash,
+    ] as const;
+  }
+
+  static from(fields: FieldsOf<L2BlockHeader>) {
+    return new L2BlockHeader(...L2BlockHeader.getFields(fields));
+  }
+
+  getSlot() {
+    return this.globalVariables.slotNumber.toBigInt();
+  }
+
+  getBlockNumber() {
+    return this.globalVariables.blockNumber;
+  }
+
+  getSize() {
+    return (
+      this.lastArchive.getSize() +
+      this.contentCommitment.getSize() +
+      this.state.getSize() +
+      this.globalVariables.getSize() +
+      this.totalFees.size +
+      this.totalManaUsed.size +
+      this.spongeBlobHash.size
+    );
+  }
+
+  toBuffer() {
+    return serializeToBuffer(...L2BlockHeader.getFields(this));
+  }
+
+  toFields(): Fr[] {
+    return serializeToFields(...L2BlockHeader.getFields(this));
+  }
+
+  clone() {
+    return L2BlockHeader.fromBuffer(this.toBuffer());
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+
+    return new L2BlockHeader(
+      reader.readObject(AppendOnlyTreeSnapshot),
+      reader.readObject(ContentCommitment),
+      reader.readObject(StateReference),
+      reader.readObject(GlobalVariables),
+      reader.readObject(Fr),
+      reader.readObject(Fr),
+      reader.readObject(Fr),
+    );
+  }
+
+  static fromFields(fields: Fr[] | FieldReader) {
+    const reader = FieldReader.asReader(fields);
+
+    return new L2BlockHeader(
+      AppendOnlyTreeSnapshot.fromFields(reader),
+      ContentCommitment.fromFields(reader),
+      StateReference.fromFields(reader),
+      GlobalVariables.fromFields(reader),
+      reader.readField(),
+      reader.readField(),
+      reader.readField(),
+    );
+  }
+
+  static empty(fields: Partial<FieldsOf<L2BlockHeader>> = {}) {
+    return L2BlockHeader.from({
+      lastArchive: AppendOnlyTreeSnapshot.empty(),
+      contentCommitment: ContentCommitment.empty(),
+      state: StateReference.empty(),
+      globalVariables: GlobalVariables.empty(),
+      totalFees: Fr.ZERO,
+      totalManaUsed: Fr.ZERO,
+      spongeBlobHash: Fr.ZERO,
+      ...fields,
+    });
+  }
+
+  isEmpty(): boolean {
+    return (
+      this.lastArchive.isEmpty() &&
+      this.contentCommitment.isEmpty() &&
+      this.state.isEmpty() &&
+      this.globalVariables.isEmpty() &&
+      this.totalFees.isZero() &&
+      this.totalManaUsed.isZero() &&
+      this.spongeBlobHash.isZero()
+    );
+  }
+
+  /**
+   * Serializes this instance into a string.
+   * @returns Encoded string.
+   */
+  public toString() {
+    return bufferToHex(this.toBuffer());
+  }
+
+  static fromString(str: string) {
+    return L2BlockHeader.fromBuffer(hexToBuffer(str));
+  }
+
+  toCheckpointHeader() {
+    return new CheckpointHeader(
+      this.lastArchive.root,
+      this.contentCommitment,
+      this.globalVariables.slotNumber,
+      this.globalVariables.timestamp,
+      this.globalVariables.coinbase,
+      this.globalVariables.feeRecipient,
+      this.globalVariables.gasFees,
+      this.totalManaUsed,
+    );
+  }
+
+  toBlockHeader() {
+    return new BlockHeader(
+      this.lastArchive,
+      this.state,
+      this.spongeBlobHash,
+      this.globalVariables,
+      this.totalFees,
+      this.totalManaUsed,
+    );
+  }
+
+  toInspect() {
+    return {
+      lastArchive: this.lastArchive.root.toString(),
+      contentCommitment: this.contentCommitment.toInspect(),
+      state: this.state.toInspect(),
+      globalVariables: this.globalVariables.toInspect(),
+      totalFees: this.totalFees.toBigInt(),
+      totalManaUsed: this.totalManaUsed.toBigInt(),
+      spongeBlobHash: this.spongeBlobHash.toString(),
+    };
+  }
+
+  [inspect.custom]() {
+    return `L2BlockHeader {
+  lastArchive: ${inspect(this.lastArchive)},
+  contentCommitment.blobsHash: ${inspect(this.contentCommitment.blobsHash)},
+  contentCommitment.inHash: ${inspect(this.contentCommitment.inHash)},
+  contentCommitment.outHash: ${inspect(this.contentCommitment.outHash)},
+  state.l1ToL2MessageTree: ${inspect(this.state.l1ToL2MessageTree)},
+  state.noteHashTree: ${inspect(this.state.partial.noteHashTree)},
+  state.nullifierTree: ${inspect(this.state.partial.nullifierTree)},
+  state.publicDataTree: ${inspect(this.state.partial.publicDataTree)},
+  globalVariables: ${inspect(this.globalVariables)},
+  totalFees: ${this.totalFees},
+  totalManaUsed: ${this.totalManaUsed},
+  spongeBlobHash: ${this.spongeBlobHash},
+}`;
+  }
+
+  public equals(other: this): boolean {
+    return (
+      this.contentCommitment.equals(other.contentCommitment) &&
+      this.state.equals(other.state) &&
+      this.globalVariables.equals(other.globalVariables) &&
+      this.totalFees.equals(other.totalFees) &&
+      this.totalManaUsed.equals(other.totalManaUsed) &&
+      this.lastArchive.equals(other.lastArchive) &&
+      this.spongeBlobHash.equals(other.spongeBlobHash)
+    );
+  }
+}

package/src/block/l2_block_info.ts

@@ -0,0 +1,63 @@
+import { Fr } from '@aztec/foundation/fields';
+import { schemas } from '@aztec/foundation/schemas';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+
+import { z } from 'zod';
+
+export type L2BlockInfo = {
+  blockHash?: Fr;
+  archive: Fr;
+  lastArchive: Fr;
+  blockNumber: number;
+  slotNumber: number;
+  txCount: number;
+  timestamp: bigint;
+};
+
+export function randomBlockInfo(blockNumber?: number): L2BlockInfo {
+  return {
+    blockHash: Fr.random(),
+    archive: Fr.random(),
+    lastArchive: Fr.random(),
+    blockNumber: blockNumber ?? Math.floor(Math.random() * 100000) + 1,
+    slotNumber: Math.floor(Math.random() * 100000) + 1,
+    txCount: Math.floor(Math.random() * 100),
+    timestamp: BigInt(Math.floor(Date.now() / 1000)),
+  };
+}
+
+export const BlockInfoSchema = z.object({
+  blockHash: schemas.Fr.optional(),
+  archive: schemas.Fr,
+  lastArchive: schemas.Fr,
+  blockNumber: z.number(),
+  slotNumber: z.number(),
+  txCount: z.number(),
+  timestamp: schemas.BigInt,
+});
+
+export function serializeBlockInfo(blockInfo: L2BlockInfo): Buffer {
+  return serializeToBuffer(
+    blockInfo.blockHash ?? Fr.ZERO,
+    blockInfo.archive,
+    blockInfo.lastArchive,
+    blockInfo.blockNumber,
+    blockInfo.slotNumber,
+    blockInfo.txCount,
+    blockInfo.timestamp,
+  );
+}
+
+export function deserializeBlockInfo(buffer: Buffer | BufferReader): L2BlockInfo {
+  const reader = BufferReader.asReader(buffer);
+  const blockHash = reader.readObject(Fr);
+  return {
+    blockHash: blockHash.equals(Fr.ZERO) ? undefined : blockHash,
+    archive: reader.readObject(Fr),
+    lastArchive: reader.readObject(Fr),
+    blockNumber: reader.readNumber(),
+    slotNumber: reader.readNumber(),
+    txCount: reader.readNumber(),
+    timestamp: reader.readBigInt(),
+  };
+}

package/src/block/l2_block_source.ts

@@ -1,15 +1,17 @@
 import type { EthAddress } from '@aztec/foundation/eth-address';
+import type { Fr } from '@aztec/foundation/fields';
+import type { TypedEventEmitter } from '@aztec/foundation/types';
 
-import type { EventEmitter } from 'events';
 import { z } from 'zod';
 
 import type { L1RollupConstants } from '../epoch-helpers/index.js';
 import type { BlockHeader } from '../tx/block_header.js';
-import type { TxEffect } from '../tx/tx_effect.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 { InBlock } from './in_block.js';
 import type { L2Block } from './l2_block.js';
+import { PublishedL2Block } from './published_l2_block.js';
+import type { ValidateBlockNegativeResult, ValidateBlockResult } from './validate_block_result.js';
 
 /**
  * Interface of classes allowing for the retrieval of L2 blocks.
@@ -62,12 +64,43 @@ export interface L2BlockSource {
    */
   getBlocks(from: number, limit: number, proven?: boolean): Promise<L2Block[]>;
 
+  /** Equivalent to getBlocks but includes publish data. */
+  getPublishedBlocks(from: number, limit: number, proven?: boolean): Promise<PublishedL2Block[]>;
+
+  /**
+   * Gets a published block by its hash.
+   * @param blockHash - The block hash to retrieve.
+   * @returns The requested published block (or undefined if not found).
+   */
+  getPublishedBlockByHash(blockHash: Fr): Promise<PublishedL2Block | undefined>;
+
+  /**
+   * Gets a published block by its archive root.
+   * @param archive - The archive root to retrieve.
+   * @returns The requested published block (or undefined if not found).
+   */
+  getPublishedBlockByArchive(archive: Fr): Promise<PublishedL2Block | undefined>;
+
+  /**
+   * 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>;
+
+  /**
+   * Gets a block header by its archive root.
+   * @param archive - The archive root to retrieve.
+   * @returns The requested block header (or undefined if not found).
+   */
+  getBlockHeaderByArchive(archive: Fr): Promise<BlockHeader | undefined>;
+
   /**
    * Gets a tx effect.
-   * @param txHash - The hash of a transaction which resulted in the returned tx effect.
-   * @returns The requested tx effect.
+   * @param txHash - The hash of the tx corresponding to the tx effect.
+   * @returns The requested tx effect with block info (or undefined if not found).
    */
-  getTxEffect(txHash: TxHash): Promise<InBlock<TxEffect> | undefined>;
+  getTxEffect(txHash: TxHash): Promise<IndexedTxEffect | undefined>;
 
   /**
    * Gets a receipt of a settled tx.
@@ -77,14 +110,14 @@ export interface L2BlockSource {
   getSettledTxReceipt(txHash: TxHash): Promise<TxReceipt | undefined>;
 
   /**
-   * Returns the current L2 slot number based on the current L1 timestamp.
+   * Returns the current L2 slot number based on the currently synced L1 timestamp.
    */
-  getL2SlotNumber(): Promise<bigint>;
+  getL2SlotNumber(): Promise<bigint | undefined>;
 
   /**
-   * Returns the current L2 epoch number based on the current L1 timestamp.
+   * Returns the current L2 epoch number based on the currently synced L1 timestamp.
    */
-  getL2EpochNumber(): Promise<bigint>;
+  getL2EpochNumber(): Promise<bigint | undefined>;
 
   /**
    * Returns all blocks for a given epoch.
@@ -93,6 +126,13 @@ export interface L2BlockSource {
    */
   getBlocksForEpoch(epochNumber: bigint): Promise<L2Block[]>;
 
+  /**
+   * Returns all block headers for a given epoch.
+   * @dev Use this method only with recent epochs, since it walks the block list backwards.
+   * @param epochNumber - The epoch number to return headers for.
+   */
+  getBlockHeadersForEpoch(epochNumber: bigint): Promise<BlockHeader[]>;
+
   /**
    * Returns whether the given epoch is completed on L1, based on the current L1 and L2 block numbers.
    * @param epochNumber - The epoch number to check.
@@ -108,13 +148,39 @@ export interface L2BlockSource {
    * Returns the rollup constants for the current chain.
    */
   getL1Constants(): Promise<L1RollupConstants>;
+
+  /** Returns values for the genesis block */
+  getGenesisValues(): Promise<{ genesisArchiveRoot: Fr }>;
+
+  /** Latest synced L1 timestamp. */
+  getL1Timestamp(): Promise<bigint | undefined>;
+
+  /**
+   * Returns whether the latest block in the pending chain on L1 is invalid (ie its attestations are incorrect).
+   * Note that invalid blocks do not get synced, so the latest block returned by the block source is always a valid one.
+   */
+  isPendingChainInvalid(): Promise<boolean>;
+
+  /**
+   * Returns the status of the pending chain validation. If the chain is invalid, reports the earliest consecutive block
+   * that is invalid, along with the reason for being invalid, which can be used to trigger an invalidation.
+   */
+  getPendingChainValidationStatus(): Promise<ValidateBlockResult>;
+
+  /** Force a sync. */
+  syncImmediate(): Promise<void>;
 }
 
 /**
  * L2BlockSource that emits events upon pending / proven chain changes.
  * see L2BlockSourceEvents for the events emitted.
  */
-export interface L2BlockSourceEventEmitter extends L2BlockSource, EventEmitter {}
+export type ArchiverEmitter = TypedEventEmitter<{
+  [L2BlockSourceEvents.L2PruneDetected]: (args: L2BlockPruneEvent) => void;
+  [L2BlockSourceEvents.L2BlockProven]: (args: L2BlockProvenEvent) => void;
+  [L2BlockSourceEvents.InvalidAttestationsBlockDetected]: (args: InvalidBlockDetectedEvent) => void;
+}>;
+export interface L2BlockSourceEventEmitter extends L2BlockSource, ArchiverEmitter {}
 
 /**
  * Identifier for L2 block tags.
@@ -130,6 +196,14 @@ export type L2Tips = Record<L2BlockTag, L2BlockId>;
 /** Identifies a block by number and hash. */
 export type L2BlockId = z.infer<typeof L2BlockIdSchema>;
 
+/** Creates an L2 block id */
+export function makeL2BlockId(number: number, hash?: string): L2BlockId {
+  if (number !== 0 && !hash) {
+    throw new Error(`Hash is required for non-genesis blocks (got block number ${number})`);
+  }
+  return { number, hash: hash! };
+}
+
 // TODO(palla/schemas): This package should know what is the block hash of the genesis block 0.
 const L2BlockIdSchema = z.union([
   z.object({
@@ -150,11 +224,24 @@ export const L2TipsSchema = z.object({
 
 export enum L2BlockSourceEvents {
   L2PruneDetected = 'l2PruneDetected',
+  L2BlockProven = 'l2BlockProven',
+  InvalidAttestationsBlockDetected = 'invalidBlockDetected',
 }
 
-export type L2BlockSourceEvent = {
-  type: 'l2PruneDetected';
+export type L2BlockProvenEvent = {
+  type: 'l2BlockProven';
   blockNumber: bigint;
   slotNumber: bigint;
   epochNumber: bigint;
 };
+
+export type L2BlockPruneEvent = {
+  type: 'l2PruneDetected';
+  epochNumber: bigint;
+  blocks: L2Block[];
+};
+
+export type InvalidBlockDetectedEvent = {
+  type: 'invalidBlockDetected';
+  validationResult: ValidateBlockNegativeResult;
+};

package/src/block/l2_block_stream/index.ts

@@ -0,0 +1,3 @@
+export * from './interfaces.js';
+export * from './l2_block_stream.js';
+export * from './l2_tips_memory_store.js';

package/src/block/l2_block_stream/interfaces.ts

@@ -0,0 +1,33 @@
+import type { L2BlockId, L2Tips } from '../l2_block_source.js';
+import type { PublishedL2Block } from '../published_l2_block.js';
+
+/** Interface to the local view of the chain. Implemented by world-state and l2-tips-store. */
+export interface L2BlockStreamLocalDataProvider {
+  getL2BlockHash(number: number): Promise<string | undefined>;
+  getL2Tips(): Promise<L2Tips>;
+}
+
+/** Interface to a handler of events emitted. */
+export interface L2BlockStreamEventHandler {
+  handleBlockStreamEvent(event: L2BlockStreamEvent): Promise<void>;
+}
+
+export type L2BlockStreamEvent =
+  | /** Emits blocks added to the chain. */ {
+      type: 'blocks-added';
+      blocks: PublishedL2Block[];
+    }
+  | /** Reports last correct block (new tip of the unproven chain). */ {
+      type: 'chain-pruned';
+      block: L2BlockId;
+    }
+  | /** Reports new proven block. */ {
+      type: 'chain-proven';
+      block: L2BlockId;
+    }
+  | /** Reports new finalized block (proven and finalized on L1). */ {
+      type: 'chain-finalized';
+      block: L2BlockId;
+    };
+
+export type L2TipsStore = L2BlockStreamEventHandler & L2BlockStreamLocalDataProvider;