@aztec/stdlib 0.0.1-fake-ceab37513c → 0.0.1-private.d0bedffd

package/src/avm/revert_code.ts

@@ -1,13 +1,29 @@
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import type { ZodFor } from '@aztec/foundation/schemas';
 import { BufferReader, FieldReader } from '@aztec/foundation/serialize';
 
 import { inspect } from 'util';
 import { z } from 'zod';
 
+/**
+ * Tracks which revertible phases of a transaction's public execution reverted.
+ *
+ * A transaction executes in three sequential phases:
+ *   1. SETUP     – non-revertible; if this fails the entire transaction is rejected.
+ *   2. APP_LOGIC – revertible; its state changes are rolled back on failure.
+ *   3. TEARDOWN  – revertible; always runs (even after app-logic revert) so the fee-payment contract can clean up.
+ *
+ * Only APP_LOGIC and TEARDOWN can produce a revert code. SETUP failures throw instead and discard the transaction
+ * entirely.
+ */
 export enum RevertCodeEnum {
+  /** All phases completed successfully; no state was rolled back. */
   OK = 0,
+  /** APP_LOGIC reverted; its state changes were discarded. If present, TEARDOWN still ran and succeeded. */
   APP_LOGIC_REVERTED = 1,
+  /** TEARDOWN reverted; its state changes were discarded. APP_LOGIC succeeded. */
   TEARDOWN_REVERTED = 2,
+  /** Both APP_LOGIC and TEARDOWN reverted; only SETUP effects are kept. */
   BOTH_REVERTED = 3,
 }
 
@@ -64,10 +80,28 @@ export class RevertCode {
     return this.code;
   }
 
-  static get schema() {
+  static get schema(): ZodFor<RevertCode> {
     return z.nativeEnum(RevertCodeEnum).transform(value => new RevertCode(value));
   }
 
+  /**
+   * Creates a RevertCode from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object, number, or RevertCode instance
+   * @returns A RevertCode instance
+   */
+  static fromPlainObject(obj: any): RevertCode {
+    if (obj instanceof RevertCode) {
+      return obj;
+    }
+    const code = typeof obj === 'number' ? obj : (obj.code ?? obj);
+    if (!isRevertCodeEnum(code)) {
+      throw new Error(`Invalid RevertCode: ${code}`);
+    }
+    return new RevertCode(code);
+  }
+
   /**
    * Having different serialization methods allows for
    * decoupling the serialization for producing the content commitment hash
@@ -96,11 +130,15 @@ export class RevertCode {
     return this.toBuffer().length;
   }
 
-  public static fromField(fr: Fr): RevertCode {
-    if (!isRevertCodeEnum(fr.toNumber())) {
-      throw new Error(`Invalid RevertCode: ${fr.toNumber()}`);
+  public static fromNumber(code: number): RevertCode {
+    if (!isRevertCodeEnum(code)) {
+      throw new Error(`Invalid RevertCode: ${code}`);
     }
-    return new RevertCode(fr.toNumber());
+    return new RevertCode(code);
+  }
+
+  public static fromField(field: Fr): RevertCode {
+    return RevertCode.fromNumber(field.toNumber());
   }
 
   public static fromFields(fields: Fr[] | FieldReader): RevertCode {
@@ -111,10 +149,7 @@ export class RevertCode {
   public static fromBuffer(buffer: Buffer | BufferReader): RevertCode {
     const reader = BufferReader.asReader(buffer);
     const code = reader.readBytes(RevertCode.PACKED_SIZE_IN_BYTES).readUInt8(0);
-    if (!isRevertCodeEnum(code)) {
-      throw new Error(`Invalid RevertCode: ${code}`);
-    }
-    return new RevertCode(code);
+    return RevertCode.fromNumber(code);
   }
 
   private static readonly NUM_OPTIONS = 4;

package/src/aztec-address/index.ts

@@ -1,10 +1,12 @@
 /* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
-import { Fr, Point, fromBuffer } from '@aztec/foundation/fields';
-import { type ZodFor, hexSchemaFor } from '@aztec/foundation/schemas';
+import { Fr, fromBuffer } from '@aztec/foundation/curves/bn254';
+import { Point } from '@aztec/foundation/curves/grumpkin';
+import { type ZodFor, bufferSchemaFor, hexSchemaFor } from '@aztec/foundation/schemas';
 import { type BufferReader, FieldReader, TypeRegistry } from '@aztec/foundation/serialize';
 import { hexToBuffer } from '@aztec/foundation/string';
 
 import { inspect } from 'util';
+import { z } from 'zod';
 
 /** Branding to ensure fields are not interchangeable types. */
 export interface AztecAddress {
@@ -71,6 +73,24 @@ export class AztecAddress {
     return new AztecAddress(hexToBuffer(buf));
   }
 
+  /**
+   * Creates an AztecAddress from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * Handles buffers, strings, or existing instances.
+   * @param obj - Plain object, buffer, string, or AztecAddress instance
+   * @returns An AztecAddress instance
+   */
+  static fromPlainObject(obj: any): AztecAddress {
+    if (obj instanceof AztecAddress) {
+      return obj;
+    }
+    if (obj instanceof Buffer || Buffer.isBuffer(obj)) {
+      return new AztecAddress(obj);
+    }
+    return AztecAddress.fromString(obj);
+  }
+
   /**
    * @returns a random valid address (i.e. one that can be encrypted to).
    */
@@ -137,7 +157,12 @@ export class AztecAddress {
   }
 
   static get schema(): ZodFor<AztecAddress> {
-    return hexSchemaFor(AztecAddress, AztecAddress.isAddress);
+    return z.union([
+      // Serialization from hex string.
+      hexSchemaFor(AztecAddress, AztecAddress.isAddress),
+      // Serialization from buffer.
+      bufferSchemaFor(AztecAddress, buf => buf.length === 32),
+    ]);
   }
 }
 

package/src/block/attestation_info.ts

@@ -1,9 +1,9 @@
-import { recoverAddress } from '@aztec/foundation/crypto';
+import { recoverAddress } from '@aztec/foundation/crypto/secp256k1-signer';
 import type { EthAddress } from '@aztec/foundation/eth-address';
 
+import { Checkpoint } from '../checkpoint/checkpoint.js';
 import { ConsensusPayload } from '../p2p/consensus_payload.js';
 import { SignatureDomainSeparator, getHashedSignaturePayloadEthSignedMessage } from '../p2p/signature_utils.js';
-import type { L2Block } from './l2_block.js';
 import type { CommitteeAttestation } from './proposal/committee_attestation.js';
 
 /**
@@ -29,17 +29,27 @@ export type AttestationInfo =
     };
 
 /**
- * Extracts attestation information from a published L2 block.
+ * Extracts attestation information from a published checkpoint.
  * Returns info for each attestation, preserving array indices.
  */
-export function getAttestationInfoFromPublishedL2Block(block: {
+export function getAttestationInfoFromPublishedCheckpoint(block: {
   attestations: CommitteeAttestation[];
-  block: L2Block;
+  checkpoint: Checkpoint;
 }): AttestationInfo[] {
-  const payload = ConsensusPayload.fromBlock(block.block);
-  const hashedPayload = getHashedSignaturePayloadEthSignedMessage(payload, SignatureDomainSeparator.blockAttestation);
+  const payload = ConsensusPayload.fromCheckpoint(block.checkpoint);
+  return getAttestationInfoFromPayload(payload, block.attestations);
+}
+
+export function getAttestationInfoFromPayload(
+  payload: ConsensusPayload,
+  attestations: CommitteeAttestation[],
+): AttestationInfo[] {
+  const hashedPayload = getHashedSignaturePayloadEthSignedMessage(
+    payload,
+    SignatureDomainSeparator.checkpointAttestation,
+  );
 
-  return block.attestations.map(attestation => {
+  return attestations.map(attestation => {
     // If signature is empty, check if we have an address directly
     if (attestation.signature.isEmpty()) {
       if (attestation.address.isZero()) {

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,44 +1,45 @@
-import { Buffer32 } from '@aztec/foundation/buffer';
-import { Fr } from '@aztec/foundation/fields';
-import { BufferReader } from '@aztec/foundation/serialize';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import type { ZodFor } from '@aztec/foundation/schemas';
 
-import { schemas } from '../schemas/schemas.js';
+import { inspect } from 'util';
+
+import { hexSchemaFor } from '../schemas/schemas.js';
+
+const BLOCK_HASH_BRAND = Symbol.for('aztec.BlockHash');
 
 /** Hash of an L2 block. */
-export class L2BlockHash extends Buffer32 {
-  constructor(
-    /** The buffer containing the hash. */
-    hash: Buffer,
-  ) {
-    super(hash);
-  }
+export class BlockHash extends Fr {
+  readonly [BLOCK_HASH_BRAND] = true as const;
 
-  static override random() {
-    return new L2BlockHash(Fr.random().toBuffer());
+  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

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

package/src/block/body.ts

@@ -1,22 +1,16 @@
-import { BLOBS_PER_BLOCK, FIELDS_PER_BLOB } from '@aztec/constants';
+import type { TxBlobData } from '@aztec/blob-lib/encoding';
 import { timesParallel } from '@aztec/foundation/collection';
-import type { Fr } from '@aztec/foundation/fields';
-import { BufferReader, FieldReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
 
 import { inspect } from 'util';
 import { z } from 'zod';
 
+import { MAX_TX_EFFECTS_PER_BODY } from '../deserialization/index.js';
 import type { ZodFor } from '../schemas/index.js';
 import { TxEffect } from '../tx/tx_effect.js';
 
 export class Body {
-  constructor(public txEffects: TxEffect[]) {
-    txEffects.forEach(txEffect => {
-      if (txEffect.isEmpty()) {
-        throw new Error('Empty tx effect not allowed in Body');
-      }
-    });
-  }
+  constructor(public txEffects: TxEffect[]) {}
 
   equals(other: Body) {
     return (
@@ -47,38 +41,22 @@ export class Body {
   static fromBuffer(buf: Buffer | BufferReader) {
     const reader = BufferReader.asReader(buf);
 
-    return new this(reader.readVector(TxEffect));
+    return new this(reader.readVector(TxEffect, MAX_TX_EFFECTS_PER_BODY));
   }
 
   /**
    * Returns a flat packed array of fields of all tx effects - used for blobs.
    */
-  toBlobFields() {
-    let flattened: Fr[] = [];
-    this.txEffects.forEach((effect: TxEffect) => {
-      flattened = flattened.concat(effect.toBlobFields());
-    });
-    if (flattened.length > BLOBS_PER_BLOCK * FIELDS_PER_BLOB) {
-      throw new Error(
-        `Attempted to overfill block's blobs with ${flattened.length} elements. The maximum is ${
-          BLOBS_PER_BLOCK * FIELDS_PER_BLOB
-        }`,
-      );
-    }
-
-    return flattened;
+  toTxBlobData(): TxBlobData[] {
+    return this.txEffects.map(txEffect => txEffect.toTxBlobData());
   }
 
   /**
    * Decodes a block from blob fields.
    */
-  static fromBlobFields(fields: Fr[]) {
-    const txEffects: TxEffect[] = [];
-    const reader = new FieldReader(fields);
-    while (!reader.isFinished()) {
-      txEffects.push(TxEffect.fromBlobFields(reader));
-    }
-    return new this(txEffects);
+  static fromTxBlobData(txBlobData: TxBlobData[]): Body {
+    const txEffects = txBlobData.map(data => TxEffect.fromTxBlobData(data));
+    return new Body(txEffects);
   }
 
   [inspect.custom]() {
@@ -87,14 +65,16 @@ export class Body {
 }`;
   }
 
-  static async random(
+  static async random({
     txsPerBlock = 4,
-    numPublicCallsPerTx = 3,
-    numPublicLogsPerCall = 1,
-    maxEffects: number | undefined = undefined,
-  ) {
-    const txEffects = await timesParallel(txsPerBlock, () =>
-      TxEffect.random(numPublicCallsPerTx, numPublicLogsPerCall, maxEffects),
+    makeTxOptions = () => ({}),
+    ...txEffectOptions
+  }: {
+    txsPerBlock?: number;
+    makeTxOptions?: (txIndex: number) => Partial<Parameters<typeof TxEffect.random>[0]>;
+  } & Partial<Parameters<typeof TxEffect.random>[0]> = {}) {
+    const txEffects = await timesParallel(txsPerBlock, txIndex =>
+      TxEffect.random({ ...makeTxOptions(txIndex), ...txEffectOptions }),
     );
 
     return new Body(txEffects);

package/src/block/checkpointed_l2_block.ts

@@ -0,0 +1,70 @@
+// Ignoring import issue to fix portable inferred type issue in zod schema
+import { CheckpointNumber, CheckpointNumberSchema } from '@aztec/foundation/branded-types';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import type { FieldsOf } from '@aztec/foundation/types';
+
+import { z } from 'zod';
+
+import { L1PublishedData } from '../checkpoint/published_checkpoint.js';
+import { MAX_BLOCK_HASH_STRING_LENGTH, MAX_COMMITTEE_SIZE } from '../deserialization/index.js';
+import { L2Block } from './l2_block.js';
+import { CommitteeAttestation } from './proposal/committee_attestation.js';
+
+/**
+ * Encapsulates an L2 Block along with the checkpoint data associated with it.
+ */
+export class CheckpointedL2Block {
+  constructor(
+    public checkpointNumber: CheckpointNumber,
+    public block: L2Block,
+    public l1: L1PublishedData,
+    public attestations: CommitteeAttestation[],
+  ) {}
+  static get schema() {
+    return z
+      .object({
+        checkpointNumber: CheckpointNumberSchema,
+        block: L2Block.schema,
+        l1: L1PublishedData.schema,
+        attestations: z.array(CommitteeAttestation.schema),
+      })
+      .transform(obj => CheckpointedL2Block.fromFields(obj));
+  }
+
+  static fromBuffer(bufferOrReader: Buffer | BufferReader): CheckpointedL2Block {
+    const reader = BufferReader.asReader(bufferOrReader);
+    const checkpointNumber = reader.readNumber();
+    const block = reader.readObject(L2Block);
+    const l1BlockNumber = reader.readBigInt();
+    const l1BlockHash = reader.readString(MAX_BLOCK_HASH_STRING_LENGTH);
+    const l1Timestamp = reader.readBigInt();
+    const attestations = reader.readVector(CommitteeAttestation, MAX_COMMITTEE_SIZE);
+    return new CheckpointedL2Block(
+      CheckpointNumber(checkpointNumber),
+      block,
+      new L1PublishedData(l1BlockNumber, l1Timestamp, l1BlockHash),
+      attestations,
+    );
+  }
+
+  static fromFields(fields: FieldsOf<CheckpointedL2Block>) {
+    return new CheckpointedL2Block(
+      CheckpointNumber(fields.checkpointNumber),
+      fields.block,
+      fields.l1,
+      fields.attestations,
+    );
+  }
+
+  public toBuffer(): Buffer {
+    return serializeToBuffer(
+      this.checkpointNumber,
+      this.block,
+      this.l1.blockNumber,
+      this.l1.blockHash,
+      this.l1.timestamp,
+      this.attestations.length,
+      this.attestations,
+    );
+  }
+}

package/src/block/in_block.ts

@@ -1,36 +1,49 @@
+import { BlockNumber, BlockNumberSchema } from '@aztec/foundation/branded-types';
+
 import { type ZodTypeAny, z } from 'zod';
 
-import { schemas } from '../schemas/index.js';
-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: BlockHash;
+};
+
 // Note: If you expand this type with indexInBlock, then delete `IndexedTxEffect` and use this type instead.
-export type InBlock<T> = {
-  l2BlockNumber: number;
-  l2BlockHash: L2BlockHash;
+export type DataInBlock<T> = {
   data: T;
-};
+} & InBlock;
+
+export function randomInBlock(): InBlock {
+  return {
+    l2BlockNumber: BlockNumber(Math.floor(Math.random() * 1000) + 1),
+    l2BlockHash: BlockHash.random(),
+  };
+}
 
-export function randomInBlock<T>(data: T): InBlock<T> {
+export function randomDataInBlock<T>(data: T): DataInBlock<T> {
   return {
+    ...randomInBlock(),
     data,
-    l2BlockNumber: Math.floor(Math.random() * 1000),
-    l2BlockHash: L2BlockHash.random(),
   };
 }
 
-export async function wrapInBlock<T>(data: T, block: L2Block): Promise<InBlock<T>> {
+export async function wrapDataInBlock<T>(data: T, block: L2Block): Promise<DataInBlock<T>> {
   return {
     data,
     l2BlockNumber: block.number,
-    l2BlockHash: L2BlockHash.fromField(await block.hash()),
+    l2BlockHash: await block.hash(),
   };
 }
 
-export function inBlockSchemaFor<T extends ZodTypeAny>(schema: T) {
+export function inBlockSchema() {
   return z.object({
-    data: schema,
-    l2BlockNumber: schemas.Integer,
-    l2BlockHash: L2BlockHash.schema,
+    l2BlockNumber: BlockNumberSchema,
+    l2BlockHash: BlockHash.schema,
   });
 }
+
+export function dataInBlockSchemaFor<T extends ZodTypeAny>(schema: T) {
+  return inBlockSchema().extend({ data: schema });
+}

package/src/block/index.ts

@@ -1,11 +1,12 @@
+export * from './block_data.js';
 export * from './l2_block.js';
 export * from './l2_block_stream/index.js';
 export * from './in_block.js';
 export * from './body.js';
-export * from './l2_block_number.js';
+export * from './block_parameter.js';
 export * from './l2_block_source.js';
 export * from './block_hash.js';
-export * from './published_l2_block.js';
+export * from './checkpointed_l2_block.js';
 export * from './proposal/index.js';
 export * from './validate_block_result.js';
 export * from './l2_block_info.js';