@aztec/stdlib 5.0.0-rc.1 → 5.0.0-rc.2

package/src/avm/avm.ts

@@ -1152,7 +1152,7 @@ export class CallStackMetadata {
 
     const { stack, leaf } = failingCall;
     const aztecCallStack = stack.map(call => ({
-      contractAddress: AztecAddress.fromField(call.contractAddress),
+      contractAddress: AztecAddress.fromFieldUnsafe(call.contractAddress),
       functionSelector: call.calldata.length > 0 ? FunctionSelector.fromFieldOrUndefined(call.calldata[0]) : undefined,
     }));
 

package/src/aztec-address/index.ts

@@ -43,34 +43,64 @@ export class AztecAddress {
   static ZERO = new AztecAddress(Buffer.alloc(32, 0));
 
   /** Null msg sender address. Not part of the protocol contracts tree. */
-  static NULL_MSG_SENDER = AztecAddress.fromBigInt(NULL_MSG_SENDER_CONTRACT_ADDRESS);
+  static NULL_MSG_SENDER = AztecAddress.fromBigIntUnsafe(NULL_MSG_SENDER_CONTRACT_ADDRESS);
 
   static zero(): AztecAddress {
     return AztecAddress.ZERO;
   }
 
-  static fromField(fr: Fr) {
+  /**
+   * Builds an `AztecAddress` from a field **without checking it is a valid address** (the x-coordinate of a point on
+   * the Grumpkin curve, which is what lets it be encrypted to). Use {@link AztecAddress.isValid} to validate an
+   * untrusted one, or {@link AztecAddress.random} for valid test addresses.
+   */
+  static fromFieldUnsafe(fr: Fr) {
     return new AztecAddress(fr);
   }
 
+  /**
+   * Deserializes an `AztecAddress` from a buffer. It does **not** check the value is a valid Grumpkin-curve address
+   * (see {@link AztecAddress.isValid}); it is meant for reading addresses from already-validated serialized data. Use
+   * {@link AztecAddress.random} for valid test addresses.
+   */
   static fromBuffer(buffer: Buffer | BufferReader) {
     return new AztecAddress(fromBuffer(buffer, Fr));
   }
 
+  /**
+   * Deserializes an `AztecAddress` from a field reader. It does **not** check the value is a valid Grumpkin-curve
+   * address (see {@link AztecAddress.isValid}); it is meant for reading addresses from already-validated serialized
+   * data. Use {@link AztecAddress.random} for valid test addresses.
+   */
   static fromFields(fields: Fr[] | FieldReader) {
     const reader = FieldReader.asReader(fields);
     return new AztecAddress(reader.readField());
   }
 
-  static fromBigInt(value: bigint) {
+  /**
+   * Builds an `AztecAddress` from a bigint **without checking it is a valid address** (the x-coordinate of a point on
+   * the Grumpkin curve, which is what lets it be encrypted to). Use {@link AztecAddress.isValid} to validate an
+   * untrusted one, or {@link AztecAddress.random} for valid test addresses.
+   */
+  static fromBigIntUnsafe(value: bigint) {
     return new AztecAddress(new Fr(value));
   }
 
-  static fromNumber(value: number) {
+  /**
+   * Builds an `AztecAddress` from a number **without checking it is a valid address** (the x-coordinate of a point on
+   * the Grumpkin curve, which is what lets it be encrypted to). Use {@link AztecAddress.isValid} to validate an
+   * untrusted one, or {@link AztecAddress.random} for valid test addresses.
+   */
+  static fromNumberUnsafe(value: number) {
     return new AztecAddress(new Fr(value));
   }
 
-  static fromString(buf: string) {
+  /**
+   * Builds an `AztecAddress` from a hex string **without checking it is a valid address** (the x-coordinate of a
+   * point on the Grumpkin curve, which is what lets it be encrypted to). Use {@link AztecAddress.isValid} to
+   * validate an untrusted one, or {@link AztecAddress.random} for valid test addresses.
+   */
+  static fromStringUnsafe(buf: string) {
     return new AztecAddress(hexToBuffer(buf));
   }
 
@@ -89,7 +119,7 @@ export class AztecAddress {
     if (obj instanceof Buffer || Buffer.isBuffer(obj)) {
       return new AztecAddress(obj);
     }
-    return AztecAddress.fromString(obj);
+    return AztecAddress.fromStringUnsafe(obj);
   }
 
   /**

package/src/block/l2_block_source.ts

@@ -241,7 +241,10 @@ export interface L2BlockSource {
 
   /**
    * Looks up a proposed (archiver-internal, not-yet-L1-confirmed) checkpoint.
-   * Returns the latest proposed entry when called with no args or `{ tag: 'proposed' }`.
+   * Returns the latest proposed entry when called with no args or `{ tag: 'proposed' }`; since a
+   * proposed entry can only be stored with a checkpoint number beyond the confirmed frontier (and is
+   * deleted on confirmation), the latest entry is always the leading one. Callers derive the proposed
+   * tip from the payload (checkpoint number, and last block `startBlock + blockCount - 1`).
    * With `{ number }` or `{ slot }`, returns the matching entry or undefined.
    * Never falls back to confirmed checkpoints.
    */
@@ -327,36 +330,29 @@ export interface L2BlockSourceEventEmitter extends L2BlockSource {
 }
 
 /**
- * Identifier for L2 block tags. Internal counterpart to {@link BlockTag} that exposes
- * the additional `proposedCheckpoint` value (used for the optimistic chain tip on the
- * archiver side) and omits `latest` (which is an alias for `proposed` accepted only at
- * the public RPC surface).
+ * Identifier for L2 block tags. Internal counterpart to {@link BlockTag} that omits `latest`
+ * (which is an alias for `proposed` accepted only at the public RPC surface).
  *
  * - proposed: Latest block proposed on L2.
- * - proposedCheckpoint: Latest block in the most recent proposed checkpoint (archiver-internal).
  * - checkpointed: Latest block whose enclosing checkpoint has been published on L1.
  * - proven: Latest block whose enclosing checkpoint has been proven on L1.
  * - finalized: Latest block whose proving L1 transaction has reached L1 finality.
- *
- * TODO(palla): Remove `proposedCheckpoint` and unify with `proposed`.
  */
-export type L2BlockTag = 'proposed' | 'proposedCheckpoint' | 'checkpointed' | 'proven' | 'finalized';
+export type L2BlockTag = 'proposed' | 'checkpointed' | 'proven' | 'finalized';
 
 /** Tips of the L2 chain. */
 export type L2Tips = {
   proposed: L2BlockId;
   checkpointed: L2TipId;
-  proposedCheckpoint: L2TipId;
   proven: L2TipId;
   finalized: L2TipId;
 };
 
 /**
- * Tips of the L2 chain as tracked by a local provider (world-state, l2-tips-store). Omits
- * `proposedCheckpoint`, which is degenerate in local stores (always equal to `checkpointed`) and
- * is only meaningful on the archiver side via {@link L2BlockSource}.
+ * Tips of the L2 chain as tracked by a local provider (world-state, l2-tips-store). Identical to
+ * {@link L2Tips}; the alias is retained for call sites that document a local-only provenance.
  */
-export type LocalL2Tips = Omit<L2Tips, 'proposedCheckpoint'>;
+export type LocalL2Tips = L2Tips;
 
 export const GENESIS_CHECKPOINT_HEADER_HASH = CheckpointHeader.empty().hash();
 
@@ -398,7 +394,6 @@ const L2TipIdSchema = z.object({
 export const L2TipsSchema = z.object({
   proposed: L2BlockIdSchema,
   checkpointed: L2TipIdSchema,
-  proposedCheckpoint: L2TipIdSchema,
   proven: L2TipIdSchema,
   finalized: L2TipIdSchema,
 });

package/src/block/l2_block_stream/interfaces.ts

@@ -1,6 +1,5 @@
 import type { BlockNumber } from '@aztec/foundation/branded-types';
 
-import type { PublishedCheckpoint } from '../../checkpoint/published_checkpoint.js';
 import type { L2Block } from '../l2_block.js';
 import type { CheckpointId, L2BlockId, L2TipId, LocalL2Tips } from '../l2_block_source.js';
 
@@ -21,7 +20,7 @@ export type LocalL2BlockId = { number: BlockNumber; hash?: string };
  */
 export type LocalChainTips = {
   proposed: LocalL2BlockId;
-  checkpointed?: { checkpoint: CheckpointId };
+  checkpointed?: { block: LocalL2BlockId; checkpoint: CheckpointId };
   proven: { block: LocalL2BlockId };
   finalized: { block: LocalL2BlockId };
 };
@@ -46,10 +45,24 @@ export type L2BlockStreamEvent =
       type: 'blocks-added';
       blocks: L2Block[];
     }
-  | /** Emits checkpoints published to L1. */ {
+  | /**
+   * Reports the new proposed tip of the chain. Emitted once per sync pass when the source's proposed tip differs
+   * from the pre-pass local one (downloads, a prune, or a thin tip movement). Carries only the block id; in block
+   * mode the corresponding payloads arrive via preceding `blocks-added` events, while in tips-only mode this is the
+   * sole signal that the proposed tip moved. Consumers that only track the proposed tip can ignore `blocks-added`
+   * entirely and anchor on this event instead.
+   */ {
+      type: 'chain-proposed';
+      block: L2BlockId;
+    }
+  | /**
+   * Reports a new checkpointed tip. Emitted at most once per sync pass when the source's checkpointed tip
+   * leads the local one. Carries only the block + checkpoint ids; consumers that need the full checkpoint
+   * payload fetch it on demand from the block source.
+   */ {
       type: 'chain-checkpointed';
-      checkpoint: PublishedCheckpoint;
       block: L2BlockId;
+      checkpoint: CheckpointId;
     }
   | /**
    * Reports last correct block (new tip of the proposed chain). Note that this is not necessarily the anchor block
@@ -77,4 +90,11 @@ export type L2BlockStreamEvent =
 
 export type L2TipsStore = L2BlockStreamEventHandler &
   L2TipsProvider &
-  Pick<L2BlockStreamLocalDataProvider, 'getL2BlockHash'>;
+  Pick<L2BlockStreamLocalDataProvider, 'getL2BlockHash'> & {
+    /**
+     * Records `(number → hash)` witnesses into the walk-back hash index without moving any tip cursor. Consumers that
+     * materialize per-height state should record a witness for each height they materialize, so a reorg below the
+     * nearest sparse anchor does not produce an over-deep prune event. See {@link L2TipsStoreBase.recordBlockHashes}.
+     */
+    recordBlockHashes(blocks: L2BlockId[]): Promise<void>;
+  };