@aztec/stdlib 0.84.0 → 0.85.0

package/dest/tx/index.js

@@ -24,6 +24,8 @@ export * from './public_simulation_output.js';
 export * from './tx_execution_request.js';
 export * from './validator/tx_validator.js';
 export * from './validator/empty_validator.js';
+export * from './validator/error_texts.js';
 export * from './capsule.js';
 export * from './global_variable_builder.js';
 export * from './hashed_values.js';
+export * from './indexed_tx_effect.js';

package/dest/tx/indexed_tx_effect.d.ts

@@ -0,0 +1,24 @@
+import { type InBlock } from '../block/in_block.js';
+import { TxEffect } from './tx_effect.js';
+export type IndexedTxEffect = InBlock<TxEffect> & {
+    txIndexInBlock: number;
+};
+export declare function indexedTxSchema(): import("zod").ZodObject<import("zod").objectUtil.extendShape<{
+    data: import("@aztec/foundation/schemas").ZodFor<TxEffect>;
+    l2BlockNumber: import("zod").ZodPipeline<import("zod").ZodUnion<[import("zod").ZodBigInt, import("zod").ZodNumber, import("zod").ZodString]>, import("zod").ZodNumber>;
+    l2BlockHash: import("zod").ZodString;
+}, {
+    txIndexInBlock: import("zod").ZodPipeline<import("zod").ZodUnion<[import("zod").ZodBigInt, import("zod").ZodNumber, import("zod").ZodString]>, import("zod").ZodNumber>;
+}>, "strip", import("zod").ZodTypeAny, {
+    data: TxEffect;
+    l2BlockNumber: number;
+    l2BlockHash: string;
+    txIndexInBlock: number;
+}, {
+    l2BlockNumber: string | number | bigint;
+    l2BlockHash: string;
+    txIndexInBlock: string | number | bigint;
+    data?: any;
+}>;
+export declare function randomIndexedTxEffect(): Promise<IndexedTxEffect>;
+//# sourceMappingURL=indexed_tx_effect.d.ts.map

package/dest/tx/indexed_tx_effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexed_tx_effect.d.ts","sourceRoot":"","sources":["../../src/tx/indexed_tx_effect.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,OAAO,EAAmC,MAAM,sBAAsB,CAAC;AACrF,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7E,wBAAgB,eAAe;;;;;;;;;;;;;;;;GAE9B;AAED,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,eAAe,CAAC,CAKtE"}

package/dest/tx/indexed_tx_effect.js

@@ -0,0 +1,14 @@
+import { schemas } from '@aztec/foundation/schemas';
+import { inBlockSchemaFor, randomInBlock } from '../block/in_block.js';
+import { TxEffect } from './tx_effect.js';
+export function indexedTxSchema() {
+    return inBlockSchemaFor(TxEffect.schema).extend({
+        txIndexInBlock: schemas.Integer
+    });
+}
+export async function randomIndexedTxEffect() {
+    return {
+        ...randomInBlock(await TxEffect.random()),
+        txIndexInBlock: Math.floor(Math.random() * 1000)
+    };
+}

package/dest/tx/tx_hash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tx_hash.d.ts","sourceRoot":"","sources":["../../src/tx/tx_hash.ts"],"names":[],"mappings":";;AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,0BAA0B,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAI3D;;GAEG;AACH,qBAAa,MAAM;IAEf,mGAAmG;aACnF,IAAI,EAAE,EAAE;;IADxB,mGAAmG;IACnF,IAAI,EAAE,EAAE;IAO1B,MAAM,CAAC,MAAM;IAIb,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,YAAY;IAKnD,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM;IAI7B,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM;IAIxB,QAAQ;IAIR,QAAQ;IAIR,QAAQ;IAIf,MAAM;IAIC,MAAM,CAAC,KAAK,EAAE,MAAM;IAI3B,MAAM,KAAK,MAAM,oMAEhB;IAED,MAAM,CAAC,IAAI;IAIX,MAAM,KAAK,IAAI,WAEd;CACF"}
+{"version":3,"file":"tx_hash.d.ts","sourceRoot":"","sources":["../../src/tx/tx_hash.ts"],"names":[],"mappings":";;AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,0BAA0B,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAI3D;;GAEG;AACH,qBAAa,MAAM;IAEf,mGAAmG;aACnF,IAAI,EAAE,EAAE;;IADxB,mGAAmG;IACnF,IAAI,EAAE,EAAE;IAG1B,MAAM,CAAC,MAAM;IAIb,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,YAAY;IAKnD,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM;IAI7B,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM;IAIxB,QAAQ;IAIR,QAAQ;IAIR,QAAQ;IAIf,MAAM;IAIC,MAAM,CAAC,KAAK,EAAE,MAAM;IAI3B,MAAM,KAAK,MAAM,oMAEhB;IAED,MAAM,CAAC,IAAI;IAIX,MAAM,KAAK,IAAI,WAEd;CACF"}

package/dest/tx/tx_hash.js

@@ -8,10 +8,7 @@ import { schemas } from '../schemas/index.js';
     constructor(/** A field representing the tx hash (tx hash is an output of poseidon hash hence it's a field). */ hash){
         this.hash = hash;
     }
-    /*
-   * TxHashes are generated from the first nullifier of a transaction, which is a Fr.
-   * @returns A random TxHash.
-   */ static random() {
+    static random() {
         return new TxHash(Fr.random());
     }
     static fromBuffer(buffer) {

package/dest/tx/validator/error_texts.d.ts

@@ -0,0 +1,20 @@
+export declare const TX_ERROR_INSUFFICIENT_FEE_PER_GAS = "Insufficient fee per gas";
+export declare const TX_ERROR_INSUFFICIENT_FEE_PAYER_BALANCE = "Insufficient fee payer balance";
+export declare const TX_ERROR_INSUFFICIENT_GAS_LIMIT = "Gas limit is below the minimum fixed cost";
+export declare const TX_ERROR_SETUP_FUNCTION_NOT_ALLOWED = "Setup function not on allow list";
+export declare const TX_ERROR_DUPLICATE_NULLIFIER_IN_TX = "Duplicate nullifier in tx";
+export declare const TX_ERROR_EXISTING_NULLIFIER = "Existing nullifier";
+export declare const TX_ERROR_INVALID_BLOCK_NUMBER = "Invalid block number";
+export declare const TX_ERROR_INCORRECT_CHAIN_ID = "Incorrect chain id";
+export declare const TX_ERROR_INCORRECT_ROLLUP_VERSION = "Incorrect rollup version";
+export declare const TX_ERROR_INVALID_PROOF = "Invalid proof";
+export declare const TX_ERROR_INCORRECT_CALLDATA = "Incorrect calldata for public call";
+export declare const TX_ERROR_CALLDATA_COUNT_MISMATCH = "Wrong number of calldata for public calls";
+export declare const TX_ERROR_CALLDATA_COUNT_TOO_LARGE = "Total calldata too large for enqueued public calls";
+export declare const TX_ERROR_CONTRACT_CLASS_LOG_COUNT = "Mismatched number of contract class logs";
+export declare const TX_ERROR_CONTRACT_CLASS_LOG_LENGTH = "Mismatched contract class logs length";
+export declare const TX_ERROR_CONTRACT_CLASS_LOGS = "Mismatched contract class logs";
+export declare const TX_ERROR_CONTRACT_CLASS_LOG_SORTING = "Incorrectly sorted contract class logs";
+export declare const TX_ERROR_BLOCK_HEADER = "Block header not found";
+export declare const TX_ERROR_DURING_VALIDATION = "Unexpected error during validation";
+//# sourceMappingURL=error_texts.d.ts.map

package/dest/tx/validator/error_texts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error_texts.d.ts","sourceRoot":"","sources":["../../../src/tx/validator/error_texts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,iCAAiC,6BAA6B,CAAC;AAC5E,eAAO,MAAM,uCAAuC,mCAAmC,CAAC;AACxF,eAAO,MAAM,+BAA+B,8CAA8C,CAAC;AAG3F,eAAO,MAAM,mCAAmC,qCAAqC,CAAC;AAGtF,eAAO,MAAM,kCAAkC,8BAA8B,CAAC;AAC9E,eAAO,MAAM,2BAA2B,uBAAuB,CAAC;AAGhE,eAAO,MAAM,6BAA6B,yBAAyB,CAAC;AACpE,eAAO,MAAM,2BAA2B,uBAAuB,CAAC;AAChE,eAAO,MAAM,iCAAiC,6BAA6B,CAAC;AAG5E,eAAO,MAAM,sBAAsB,kBAAkB,CAAC;AAGtD,eAAO,MAAM,2BAA2B,uCAAuC,CAAC;AAChF,eAAO,MAAM,gCAAgC,8CAA8C,CAAC;AAC5F,eAAO,MAAM,iCAAiC,uDAAuD,CAAC;AACtG,eAAO,MAAM,iCAAiC,6CAA6C,CAAC;AAC5F,eAAO,MAAM,kCAAkC,0CAA0C,CAAC;AAC1F,eAAO,MAAM,4BAA4B,mCAAmC,CAAC;AAC7E,eAAO,MAAM,mCAAmC,2CAA2C,CAAC;AAG5F,eAAO,MAAM,qBAAqB,2BAA2B,CAAC;AAG9D,eAAO,MAAM,0BAA0B,uCAAuC,CAAC"}

package/dest/tx/validator/error_texts.js

@@ -0,0 +1,27 @@
+// Gas and fees
+export const TX_ERROR_INSUFFICIENT_FEE_PER_GAS = 'Insufficient fee per gas';
+export const TX_ERROR_INSUFFICIENT_FEE_PAYER_BALANCE = 'Insufficient fee payer balance';
+export const TX_ERROR_INSUFFICIENT_GAS_LIMIT = 'Gas limit is below the minimum fixed cost';
+// Phases
+export const TX_ERROR_SETUP_FUNCTION_NOT_ALLOWED = 'Setup function not on allow list';
+// Nullifiers
+export const TX_ERROR_DUPLICATE_NULLIFIER_IN_TX = 'Duplicate nullifier in tx';
+export const TX_ERROR_EXISTING_NULLIFIER = 'Existing nullifier';
+// Metadata
+export const TX_ERROR_INVALID_BLOCK_NUMBER = 'Invalid block number';
+export const TX_ERROR_INCORRECT_CHAIN_ID = 'Incorrect chain id';
+export const TX_ERROR_INCORRECT_ROLLUP_VERSION = 'Incorrect rollup version';
+// Proof
+export const TX_ERROR_INVALID_PROOF = 'Invalid proof';
+//Data
+export const TX_ERROR_INCORRECT_CALLDATA = 'Incorrect calldata for public call';
+export const TX_ERROR_CALLDATA_COUNT_MISMATCH = 'Wrong number of calldata for public calls';
+export const TX_ERROR_CALLDATA_COUNT_TOO_LARGE = 'Total calldata too large for enqueued public calls';
+export const TX_ERROR_CONTRACT_CLASS_LOG_COUNT = 'Mismatched number of contract class logs';
+export const TX_ERROR_CONTRACT_CLASS_LOG_LENGTH = 'Mismatched contract class logs length';
+export const TX_ERROR_CONTRACT_CLASS_LOGS = 'Mismatched contract class logs';
+export const TX_ERROR_CONTRACT_CLASS_LOG_SORTING = 'Incorrectly sorted contract class logs';
+// Block header
+export const TX_ERROR_BLOCK_HEADER = 'Block header not found';
+// General
+export const TX_ERROR_DURING_VALIDATION = 'Unexpected error during validation';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/stdlib",
-  "version": "0.84.0",
+  "version": "0.85.0",
   "type": "module",
   "inherits": [
     "../package.common.json",
@@ -39,6 +39,7 @@
     "./stats": "./dest/stats/index.js",
     "./auth-witness": "./dest/auth_witness/index.js",
     "./block": "./dest/block/index.js",
+    "./block/test": "./dest/block/test/index.js",
     "./versioning": "./dest/versioning/index.js",
     "./interfaces/client": "./dest/interfaces/client.js",
     "./interfaces/server": "./dest/interfaces/server.js",
@@ -67,11 +68,11 @@
     "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}"
   },
   "dependencies": {
-    "@aztec/bb.js": "0.84.0",
-    "@aztec/blob-lib": "0.84.0",
-    "@aztec/constants": "0.84.0",
-    "@aztec/ethereum": "0.84.0",
-    "@aztec/foundation": "0.84.0",
+    "@aztec/bb.js": "0.85.0",
+    "@aztec/blob-lib": "0.85.0",
+    "@aztec/constants": "0.85.0",
+    "@aztec/ethereum": "0.85.0",
+    "@aztec/foundation": "0.85.0",
     "@google-cloud/storage": "^7.15.0",
     "lodash.chunk": "^4.2.0",
     "lodash.isequal": "^4.5.0",
@@ -84,6 +85,7 @@
     "zod": "^3.23.8"
   },
   "devDependencies": {
+    "@jest/expect": "^29.5.0",
     "@jest/globals": "^29.5.0",
     "@types/jest": "^29.5.0",
     "@types/lodash.chunk": "^4.2.9",

package/src/avm/avm.ts

@@ -10,7 +10,7 @@ import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
 import { MerkleTreeId } from '../trees/merkle_tree_id.js';
 import { NullifierLeafPreimage } from '../trees/nullifier_leaf.js';
 import { PublicDataTreeLeafPreimage } from '../trees/public_data_leaf.js';
-import type { Tx } from '../tx/index.js';
+import { GlobalVariables, TreeSnapshots, type Tx } from '../tx/index.js';
 import { AvmCircuitPublicInputs } from './avm_circuit_public_inputs.js';
 import { serializeWithMessagePack } from './message_pack.js';
 
@@ -262,6 +262,117 @@ function AvmSequentialInsertHintFactory(klass: IndexedTreeLeafPreimagesClasses)
 export class AvmSequentialInsertHintPublicDataTree extends AvmSequentialInsertHintFactory(PublicDataTreeLeafPreimage) {}
 export class AvmSequentialInsertHintNullifierTree extends AvmSequentialInsertHintFactory(NullifierLeafPreimage) {}
 
+// Hint for MerkleTreeDB.appendLeaves.
+// Note: only supported for NOTE_HASH_TREE and L1_TO_L2_MESSAGE_TREE.
+export class AvmAppendLeavesHint {
+  constructor(
+    public readonly hintKey: AppendOnlyTreeSnapshot,
+    public readonly stateAfter: AppendOnlyTreeSnapshot,
+    // params
+    public readonly treeId: MerkleTreeId,
+    public readonly leaves: Fr[],
+  ) {}
+
+  static get schema() {
+    return z
+      .object({
+        hintKey: AppendOnlyTreeSnapshot.schema,
+        stateAfter: AppendOnlyTreeSnapshot.schema,
+        treeId: z.number().int().nonnegative(),
+        leaves: schemas.Fr.array(),
+      })
+      .transform(
+        ({ hintKey, stateAfter, treeId, leaves }) => new AvmAppendLeavesHint(hintKey, stateAfter, treeId, leaves),
+      );
+  }
+}
+
+// Hint for checkpoint actions that don't change the state.
+class AvmCheckpointActionNoStateChangeHint {
+  constructor(
+    // key
+    public readonly actionCounter: number,
+    // current checkpoint evolution
+    public readonly oldCheckpointId: number,
+    public readonly newCheckpointId: number,
+  ) {}
+
+  static get schema() {
+    return z
+      .object({
+        actionCounter: z.number().int().nonnegative(),
+        oldCheckpointId: z.number().int().nonnegative(),
+        newCheckpointId: z.number().int().nonnegative(),
+      })
+      .transform(
+        ({ actionCounter, oldCheckpointId, newCheckpointId }) =>
+          new AvmCheckpointActionNoStateChangeHint(actionCounter, oldCheckpointId, newCheckpointId),
+      );
+  }
+}
+
+// Hint for MerkleTreeDB.createCheckpoint.
+export class AvmCreateCheckpointHint extends AvmCheckpointActionNoStateChangeHint {}
+
+// Hint for MerkleTreeDB.commitCheckpoint.
+export class AvmCommitCheckpointHint extends AvmCheckpointActionNoStateChangeHint {}
+
+// Hint for MerkleTreeDB.revertCheckpoint.
+export class AvmRevertCheckpointHint {
+  // We use explicit fields for MessagePack.
+  constructor(
+    // key
+    public readonly actionCounter: number,
+    // current checkpoint evolution
+    public readonly oldCheckpointId: number,
+    public readonly newCheckpointId: number,
+    // state evolution
+    public readonly stateBefore: TreeSnapshots,
+    public readonly stateAfter: TreeSnapshots,
+  ) {}
+
+  static create(
+    actionCounter: number,
+    oldCheckpointId: number,
+    newCheckpointId: number,
+    stateBefore: Record<MerkleTreeId, AppendOnlyTreeSnapshot>,
+    stateAfter: Record<MerkleTreeId, AppendOnlyTreeSnapshot>,
+  ): AvmRevertCheckpointHint {
+    return new AvmRevertCheckpointHint(
+      actionCounter,
+      oldCheckpointId,
+      newCheckpointId,
+      new TreeSnapshots(
+        stateBefore[MerkleTreeId.L1_TO_L2_MESSAGE_TREE],
+        stateBefore[MerkleTreeId.NOTE_HASH_TREE],
+        stateBefore[MerkleTreeId.NULLIFIER_TREE],
+        stateBefore[MerkleTreeId.PUBLIC_DATA_TREE],
+      ),
+      new TreeSnapshots(
+        stateAfter[MerkleTreeId.L1_TO_L2_MESSAGE_TREE],
+        stateAfter[MerkleTreeId.NOTE_HASH_TREE],
+        stateAfter[MerkleTreeId.NULLIFIER_TREE],
+        stateAfter[MerkleTreeId.PUBLIC_DATA_TREE],
+      ),
+    );
+  }
+
+  static get schema() {
+    return z
+      .object({
+        actionCounter: z.number().int().nonnegative(),
+        oldCheckpointId: z.number().int().nonnegative(),
+        newCheckpointId: z.number().int().nonnegative(),
+        stateBefore: TreeSnapshots.schema,
+        stateAfter: TreeSnapshots.schema,
+      })
+      .transform(
+        ({ actionCounter, oldCheckpointId, newCheckpointId, stateBefore, stateAfter }) =>
+          new AvmRevertCheckpointHint(actionCounter, oldCheckpointId, newCheckpointId, stateBefore, stateAfter),
+      );
+  }
+}
+
 ////////////////////////////////////////////////////////////////////////////
 // Hints (other)
 ////////////////////////////////////////////////////////////////////////////
@@ -290,6 +401,8 @@ export class AvmEnqueuedCallHint {
 
 export class AvmTxHint {
   constructor(
+    public readonly hash: string,
+    public readonly globalVariables: GlobalVariables,
     public readonly nonRevertibleAccumulatedData: {
       noteHashes: Fr[];
       nullifiers: Fr[];
@@ -307,12 +420,17 @@ export class AvmTxHint {
     public readonly teardownEnqueuedCall: AvmEnqueuedCallHint | null,
   ) {}
 
-  static fromTx(tx: Tx): AvmTxHint {
+  static async fromTx(tx: Tx): Promise<AvmTxHint> {
     const setupCallRequests = tx.getNonRevertiblePublicCallRequestsWithCalldata();
     const appLogicCallRequests = tx.getRevertiblePublicCallRequestsWithCalldata();
     const teardownCallRequest = tx.getTeardownPublicCallRequestWithCalldata();
 
+    // For informational purposes. Assumed quick because it should be cached.
+    const txHash = await tx.getTxHash();
+
     return new AvmTxHint(
+      txHash.hash.toString(),
+      tx.data.constants.historicalHeader.globalVariables,
       {
         noteHashes: tx.data.forPublic!.nonRevertibleAccumulatedData.noteHashes.filter(x => !x.isZero()),
         nullifiers: tx.data.forPublic!.nonRevertibleAccumulatedData.nullifiers.filter(x => !x.isZero()),
@@ -351,23 +469,54 @@ export class AvmTxHint {
   }
 
   static empty() {
-    return new AvmTxHint({ noteHashes: [], nullifiers: [] }, { noteHashes: [], nullifiers: [] }, [], [], null);
+    return new AvmTxHint(
+      '',
+      GlobalVariables.empty(),
+      { noteHashes: [], nullifiers: [] },
+      { noteHashes: [], nullifiers: [] },
+      [],
+      [],
+      null,
+    );
   }
 
   static get schema() {
-    return z.object({
-      nonRevertibleAccumulatedData: z.object({
-        noteHashes: schemas.Fr.array(),
-        nullifiers: schemas.Fr.array(),
-      }),
-      revertibleAccumulatedData: z.object({
-        noteHashes: schemas.Fr.array(),
-        nullifiers: schemas.Fr.array(),
-      }),
-      setupEnqueuedCalls: AvmEnqueuedCallHint.schema.array(),
-      appLogicEnqueuedCalls: AvmEnqueuedCallHint.schema.array(),
-      teardownEnqueuedCall: AvmEnqueuedCallHint.schema.nullable(),
-    });
+    return z
+      .object({
+        hash: z.string(),
+        globalVariables: GlobalVariables.schema,
+        nonRevertibleAccumulatedData: z.object({
+          noteHashes: schemas.Fr.array(),
+          nullifiers: schemas.Fr.array(),
+        }),
+        revertibleAccumulatedData: z.object({
+          noteHashes: schemas.Fr.array(),
+          nullifiers: schemas.Fr.array(),
+        }),
+        setupEnqueuedCalls: AvmEnqueuedCallHint.schema.array(),
+        appLogicEnqueuedCalls: AvmEnqueuedCallHint.schema.array(),
+        teardownEnqueuedCall: AvmEnqueuedCallHint.schema.nullable(),
+      })
+      .transform(
+        ({
+          hash,
+          globalVariables,
+          nonRevertibleAccumulatedData,
+          revertibleAccumulatedData,
+          setupEnqueuedCalls,
+          appLogicEnqueuedCalls,
+          teardownEnqueuedCall,
+        }) =>
+          new AvmTxHint(
+            hash,
+            globalVariables,
+            nonRevertibleAccumulatedData,
+            revertibleAccumulatedData,
+            setupEnqueuedCalls,
+            appLogicEnqueuedCalls,
+            teardownEnqueuedCall,
+          ),
+      );
   }
 }
 
@@ -379,6 +528,7 @@ export class AvmExecutionHints {
     public readonly contractClasses: AvmContractClassHint[] = [],
     public readonly bytecodeCommitments: AvmBytecodeCommitmentHint[] = [],
     // Merkle DB hints.
+    public startingTreeRoots: TreeSnapshots = TreeSnapshots.empty(),
     public readonly getSiblingPathHints: AvmGetSiblingPathHint[] = [],
     public readonly getPreviousValueIndexHints: AvmGetPreviousValueIndexHint[] = [],
     public readonly getLeafPreimageHintsPublicDataTree: AvmGetLeafPreimageHintPublicDataTree[] = [],
@@ -386,6 +536,10 @@ export class AvmExecutionHints {
     public readonly getLeafValueHints: AvmGetLeafValueHint[] = [],
     public readonly sequentialInsertHintsPublicDataTree: AvmSequentialInsertHintPublicDataTree[] = [],
     public readonly sequentialInsertHintsNullifierTree: AvmSequentialInsertHintNullifierTree[] = [],
+    public readonly appendLeavesHints: AvmAppendLeavesHint[] = [],
+    public readonly createCheckpointHints: AvmCreateCheckpointHint[] = [],
+    public readonly commitCheckpointHints: AvmCommitCheckpointHint[] = [],
+    public readonly revertCheckpointHints: AvmRevertCheckpointHint[] = [],
   ) {}
 
   static empty() {
@@ -399,6 +553,7 @@ export class AvmExecutionHints {
         contractInstances: AvmContractInstanceHint.schema.array(),
         contractClasses: AvmContractClassHint.schema.array(),
         bytecodeCommitments: AvmBytecodeCommitmentHint.schema.array(),
+        startingTreeRoots: TreeSnapshots.schema,
         getSiblingPathHints: AvmGetSiblingPathHint.schema.array(),
         getPreviousValueIndexHints: AvmGetPreviousValueIndexHint.schema.array(),
         getLeafPreimageHintsPublicDataTree: AvmGetLeafPreimageHintPublicDataTree.schema.array(),
@@ -406,6 +561,10 @@ export class AvmExecutionHints {
         getLeafValueHints: AvmGetLeafValueHint.schema.array(),
         sequentialInsertHintsPublicDataTree: AvmSequentialInsertHintPublicDataTree.schema.array(),
         sequentialInsertHintsNullifierTree: AvmSequentialInsertHintNullifierTree.schema.array(),
+        appendLeavesHints: AvmAppendLeavesHint.schema.array(),
+        createCheckpointHints: AvmCreateCheckpointHint.schema.array(),
+        commitCheckpointHints: AvmCommitCheckpointHint.schema.array(),
+        revertCheckpointHints: AvmRevertCheckpointHint.schema.array(),
       })
       .transform(
         ({
@@ -413,6 +572,7 @@ export class AvmExecutionHints {
           contractInstances,
           contractClasses,
           bytecodeCommitments,
+          startingTreeRoots,
           getSiblingPathHints,
           getPreviousValueIndexHints,
           getLeafPreimageHintsPublicDataTree,
@@ -420,12 +580,17 @@ export class AvmExecutionHints {
           getLeafValueHints,
           sequentialInsertHintsPublicDataTree,
           sequentialInsertHintsNullifierTree,
+          appendLeavesHints,
+          createCheckpointHints,
+          commitCheckpointHints,
+          revertCheckpointHints,
         }) =>
           new AvmExecutionHints(
             tx,
             contractInstances,
             contractClasses,
             bytecodeCommitments,
+            startingTreeRoots,
             getSiblingPathHints,
             getPreviousValueIndexHints,
             getLeafPreimageHintsPublicDataTree,
@@ -433,35 +598,29 @@ export class AvmExecutionHints {
             getLeafValueHints,
             sequentialInsertHintsPublicDataTree,
             sequentialInsertHintsNullifierTree,
+            appendLeavesHints,
+            createCheckpointHints,
+            commitCheckpointHints,
+            revertCheckpointHints,
           ),
       );
   }
 }
 
 export class AvmCircuitInputs {
-  constructor(
-    public readonly functionName: string, // only informational
-    public readonly calldata: Fr[],
-    public readonly hints: AvmExecutionHints,
-    public publicInputs: AvmCircuitPublicInputs,
-  ) {}
+  constructor(public readonly hints: AvmExecutionHints, public publicInputs: AvmCircuitPublicInputs) {}
 
   static empty() {
-    return new AvmCircuitInputs('', [], AvmExecutionHints.empty(), AvmCircuitPublicInputs.empty());
+    return new AvmCircuitInputs(AvmExecutionHints.empty(), AvmCircuitPublicInputs.empty());
   }
 
   static get schema() {
     return z
       .object({
-        functionName: z.string(),
-        calldata: schemas.Fr.array(),
         hints: AvmExecutionHints.schema,
         publicInputs: AvmCircuitPublicInputs.schema,
       })
-      .transform(
-        ({ functionName, calldata, hints, publicInputs }) =>
-          new AvmCircuitInputs(functionName, calldata, hints, publicInputs),
-      );
+      .transform(({ hints, publicInputs }) => new AvmCircuitInputs(hints, publicInputs));
   }
 
   public serializeWithMessagePack(): Buffer {

package/src/block/in_block.ts

@@ -5,6 +5,7 @@ import { type ZodTypeAny, z } from 'zod';
 import { schemas } from '../schemas/index.js';
 import type { L2Block } from './l2_block.js';
 
+// Note: If you expand this type with indexInBlock, then delete `IndexedTxEffect` and use this type instead.
 export type InBlock<T> = {
   l2BlockNumber: number;
   l2BlockHash: string;

package/src/block/index.ts

@@ -1,5 +1,5 @@
 export * from './l2_block.js';
-export * from './l2_block_downloader/index.js';
+export * from './l2_block_stream/index.js';
 export * from './in_block.js';
 export * from './body.js';
 export * from './l2_block_number.js';

package/src/block/l2_block_source.ts

@@ -5,10 +5,9 @@ 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 type { PublishedL2Block } from './published_l2_block.js';
 
@@ -68,10 +67,10 @@ export interface L2BlockSource {
 
   /**
    * 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.
@@ -119,6 +118,9 @@ export interface L2BlockSource {
    * Returns the rollup constants for the current chain.
    */
   getL1Constants(): Promise<L1RollupConstants>;
+
+  /** Force a sync. */
+  syncImmediate(): Promise<void>;
 }
 
 /**
@@ -141,6 +143,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({

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;