refactor(fast-inbox)!: answer L1-to-L2 message readiness from the message leaf index (A-1388)

Blocks consume Inbox messages in order into consecutive L1-to-L2 tree leaves, so a message is
available at a tip exactly when that tip's leaf count has grown past the message's index — one
comparison against data every block header already carries. `isL1ToL2MessageReady` now does that
via `getL1ToL2MessageIndex`, which also drops its stale claim that messages land in the first block
of a checkpoint. The `getL1ToL2MessageCheckpoint` node RPC method existed only to answer this
question and needed a binary search over block records to do it, so delete it: node service,
world-state queries, interface, schema, and its callers. `getL1ToL2MessageIndex` takes its place in
the operator API reference.

Author: spalladino

docs/docs-operate/operators/reference/node-api-reference.md

@@ -635,22 +635,24 @@ curl -X POST http://localhost:8080 \
   -d '{"jsonrpc":"2.0","method":"aztec_getL1ToL2MessageMembershipWitness","params":["latest","0x1234..."],"id":1}'
 ```
 
-### aztec_getL1ToL2MessageCheckpoint
+### aztec_getL1ToL2MessageIndex
 
-Returns the L2 checkpoint number in which this L1 to L2 message becomes available, or undefined if not found.
+Returns the compact leaf index assigned to this L1 to L2 message as soon as the node has ingested it from L1,
+before any L2 block consumes it. Returns undefined if the node has not yet seen the message. The message becomes
+consumable once a block's L1-to-L2 message tree grows past this index.
 
 **Parameters**:
 
 1. `l1ToL2Message` - `Fr`
 
-**Returns**: `number | undefined`
+**Returns**: `bigint | undefined`
 
 **Example**:
 
 ```bash
 curl -X POST http://localhost:8080 \
   -H 'Content-Type: application/json' \
-  -d '{"jsonrpc":"2.0","method":"aztec_getL1ToL2MessageCheckpoint","params":["0x1234..."],"id":1}'
+  -d '{"jsonrpc":"2.0","method":"aztec_getL1ToL2MessageIndex","params":["0x1234..."],"id":1}'
 ```
 
 ### aztec_getL2ToL1MembershipWitness

docs/scripts/node_api_reference_generation/generate_node_api_reference.ts

@@ -559,7 +559,7 @@ const METHOD_GROUPS: { heading: string; namespace: string; methods: string[] }[]
     namespace: 'aztec',
     methods: [
       'getL1ToL2MessageMembershipWitness',
-      'getL1ToL2MessageCheckpoint',
+      'getL1ToL2MessageIndex',
       'getL2ToL1MembershipWitness',
       'getL2ToL1Messages',
     ],

yarn-project/aztec-node/src/aztec-node/server.test.ts

@@ -1568,27 +1568,19 @@ describe('aztec node', () => {
     });
   });
 
-  describe('getL1ToL2MessageCheckpoint', () => {
-    it('returns the checkpoint of the block that consumed the message', async () => {
+  describe('getL1ToL2MessageIndex', () => {
+    it('returns the compact leaf index the node assigned to the message', async () => {
       const msg = Fr.random();
-      l1ToL2MessageSource.getL1ToL2MessageIndex.mockResolvedValue(0n);
-      // The first block (checkpoint 1) consumed message index 0: its L1-to-L2 tree leaf count is 1 > 0.
-      l2BlockSource.getBlockNumber.mockResolvedValue(BlockNumber(1));
-      l2BlockSource.getBlockData.mockResolvedValue({
-        checkpointNumber: CheckpointNumber(1),
-        header: { state: { l1ToL2MessageTree: { nextAvailableLeafIndex: 1 } } },
-      } as unknown as BlockData);
+      l1ToL2MessageSource.getL1ToL2MessageIndex.mockResolvedValue(7n);
 
-      const result = await node.getL1ToL2MessageCheckpoint(msg);
-      expect(result).toEqual(CheckpointNumber(1));
+      expect(await node.getL1ToL2MessageIndex(msg)).toEqual(7n);
     });
 
     it('returns undefined when the message is not found', async () => {
       const msg = Fr.random();
       l1ToL2MessageSource.getL1ToL2MessageIndex.mockResolvedValue(undefined);
 
-      const result = await node.getL1ToL2MessageCheckpoint(msg);
-      expect(result).toBeUndefined();
+      expect(await node.getL1ToL2MessageIndex(msg)).toBeUndefined();
     });
   });
 

yarn-project/aztec-node/src/aztec-node/server.ts

@@ -673,10 +673,6 @@ export class AztecNodeService implements AztecNode, AztecNodeAdmin, AztecNodeDeb
     return this.worldStateQueries.getL1ToL2MessageMembershipWitness(referenceBlock, l1ToL2Message);
   }
 
-  public getL1ToL2MessageCheckpoint(l1ToL2Message: Fr): Promise<CheckpointNumber | undefined> {
-    return this.worldStateQueries.getL1ToL2MessageCheckpoint(l1ToL2Message);
-  }
-
   public getL1ToL2MessageIndex(l1ToL2Message: Fr): Promise<bigint | undefined> {
     return this.worldStateQueries.getL1ToL2MessageIndex(l1ToL2Message);
   }

yarn-project/aztec-node/src/modules/node_world_state_queries.ts

@@ -1,18 +1,12 @@
-import {
-  ARCHIVE_HEIGHT,
-  INITIAL_L2_BLOCK_NUM,
-  type L1_TO_L2_MSG_TREE_HEIGHT,
-  type NOTE_HASH_TREE_HEIGHT,
-} from '@aztec/constants';
-import { BlockNumber, type CheckpointNumber, type EpochNumber } from '@aztec/foundation/branded-types';
+import { ARCHIVE_HEIGHT, type L1_TO_L2_MSG_TREE_HEIGHT, type NOTE_HASH_TREE_HEIGHT } from '@aztec/constants';
+import { BlockNumber, type EpochNumber } from '@aztec/foundation/branded-types';
 import { chunkBy } from '@aztec/foundation/collection';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { type Logger, createLogger } from '@aztec/foundation/log';
 import { sleep } from '@aztec/foundation/sleep';
 import { MembershipWitness, type SiblingPath } from '@aztec/foundation/trees';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 import {
-  type BlockData,
   type BlockHash,
   type BlockParameter,
   type DataInBlock,
@@ -187,39 +181,6 @@ export class NodeWorldStateQueries {
     return this.l1ToL2MessageSource.getL1ToL2MessageIndex(l1ToL2Message);
   }
 
-  public async getL1ToL2MessageCheckpoint(l1ToL2Message: Fr): Promise<CheckpointNumber | undefined> {
-    const messageIndex = await this.l1ToL2MessageSource.getL1ToL2MessageIndex(l1ToL2Message);
-    if (messageIndex === undefined) {
-      return undefined;
-    }
-    // Post-flip, an L1-to-L2 message at compact leaf index `i` is consumed by the first block whose L1-to-L2 tree leaf
-    // count exceeds `i` (leaf counts are monotonic in block number); that block's checkpoint is the answer, sourced
-    // from the stored block records rather than 1024-per-checkpoint index arithmetic (AZIP-22 Fast Inbox).
-    const block = await this.#findBlockConsumingL1ToL2MessageIndex(messageIndex);
-    return block?.checkpointNumber;
-  }
-
-  /** Binary-searches the block records for the first block whose L1-to-L2 tree leaf count exceeds `messageIndex`. */
-  async #findBlockConsumingL1ToL2MessageIndex(messageIndex: bigint): Promise<BlockData | undefined> {
-    let lo: number = INITIAL_L2_BLOCK_NUM;
-    let hi: number = await this.blockSource.getBlockNumber();
-    let result: BlockData | undefined;
-    while (lo <= hi) {
-      const mid = lo + Math.floor((hi - lo) / 2);
-      const block = await this.blockSource.getBlockData({ number: BlockNumber(mid) });
-      if (block === undefined) {
-        break;
-      }
-      if (BigInt(block.header.state.l1ToL2MessageTree.nextAvailableLeafIndex) > messageIndex) {
-        result = block;
-        hi = mid - 1;
-      } else {
-        lo = mid + 1;
-      }
-    }
-    return result;
-  }
-
   /**
    * Returns all the L2 to L1 messages in an epoch (empty array if the epoch is not found). The public
    * `AztecNodeService.getL2ToL1Messages` that delegates here is deprecated in favor of

yarn-project/aztec.js/src/utils/cross_chain.test.ts

@@ -1,4 +1,3 @@
-import { CheckpointNumber } from '@aztec/foundation/branded-types';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import type { BlockData } from '@aztec/stdlib/block';
 import type { AztecNode } from '@aztec/stdlib/interfaces/client';
@@ -8,44 +7,45 @@ import { type MockProxy, mock } from 'jest-mock-extended';
 import { isL1ToL2MessageReady } from './cross_chain.js';
 
 describe('isL1ToL2MessageReady', () => {
-  let node: MockProxy<Pick<AztecNode, 'getBlockData' | 'getL1ToL2MessageCheckpoint'>>;
+  let node: MockProxy<Pick<AztecNode, 'getBlockData' | 'getL1ToL2MessageIndex'>>;
   let messageHash: Fr;
 
-  const blockAtCheckpoint = (checkpointNumber: number) =>
-    ({ checkpointNumber: CheckpointNumber(checkpointNumber) }) as BlockData;
+  /** A block whose L1-to-L2 message tree holds `leafCount` leaves, i.e. leaf indices 0..leafCount-1. */
+  const blockWithMessageLeaves = (leafCount: number) =>
+    ({ header: { state: { l1ToL2MessageTree: { nextAvailableLeafIndex: leafCount } } } }) as BlockData;
 
   beforeEach(() => {
     node = mock();
     messageHash = Fr.random();
   });
 
-  it('returns false when the message is not yet in any checkpoint', async () => {
-    node.getL1ToL2MessageCheckpoint.mockResolvedValue(undefined);
+  it('returns false when the node has not seen the message yet', async () => {
+    node.getL1ToL2MessageIndex.mockResolvedValue(undefined);
 
     expect(await isL1ToL2MessageReady(node, messageHash)).toBe(false);
     expect(node.getBlockData).not.toHaveBeenCalled();
   });
 
   describe('latest fallback (no chain tip)', () => {
     beforeEach(() => {
-      node.getL1ToL2MessageCheckpoint.mockResolvedValue(CheckpointNumber(5));
+      node.getL1ToL2MessageIndex.mockResolvedValue(5n);
     });
 
-    it('checks readiness against the latest block', async () => {
-      node.getBlockData.mockResolvedValue(blockAtCheckpoint(5));
+    it('returns true once the latest block has consumed the message leaf', async () => {
+      node.getBlockData.mockResolvedValue(blockWithMessageLeaves(6));
 
       expect(await isL1ToL2MessageReady(node, messageHash)).toBe(true);
       expect(node.getBlockData).toHaveBeenCalledWith('latest');
     });
 
-    it('returns true once the latest block reaches the message checkpoint', async () => {
-      node.getBlockData.mockResolvedValue(blockAtCheckpoint(6));
+    it('returns false when the latest block stops exactly at the message leaf', async () => {
+      node.getBlockData.mockResolvedValue(blockWithMessageLeaves(5));
 
-      expect(await isL1ToL2MessageReady(node, messageHash)).toBe(true);
+      expect(await isL1ToL2MessageReady(node, messageHash)).toBe(false);
     });
 
-    it('returns false when the latest block is behind the message checkpoint', async () => {
-      node.getBlockData.mockResolvedValue(blockAtCheckpoint(4));
+    it('returns false when the latest block is behind the message leaf', async () => {
+      node.getBlockData.mockResolvedValue(blockWithMessageLeaves(4));
 
       expect(await isL1ToL2MessageReady(node, messageHash)).toBe(false);
     });
@@ -59,23 +59,23 @@ describe('isL1ToL2MessageReady', () => {
 
   describe('with an explicit chain tip', () => {
     beforeEach(() => {
-      node.getL1ToL2MessageCheckpoint.mockResolvedValue(CheckpointNumber(5));
+      node.getL1ToL2MessageIndex.mockResolvedValue(5n);
     });
 
     it('compares against the requested tip instead of latest', async () => {
-      // The proven tip lags behind latest: the message is in checkpoint 5 but proven is only at 4.
+      // The proven tip lags behind latest: latest consumed the message leaf, proven has not.
       node.getBlockData.mockImplementation(param =>
-        Promise.resolve(param === 'proven' ? blockAtCheckpoint(4) : blockAtCheckpoint(6)),
+        Promise.resolve(param === 'proven' ? blockWithMessageLeaves(5) : blockWithMessageLeaves(7)),
       );
 
       expect(await isL1ToL2MessageReady(node, messageHash, 'latest')).toBe(true);
       expect(await isL1ToL2MessageReady(node, messageHash, 'proven')).toBe(false);
       expect(node.getBlockData).toHaveBeenLastCalledWith('proven');
     });
 
-    it('returns true once the requested tip reaches the message checkpoint', async () => {
+    it('returns true once the requested tip has consumed the message leaf', async () => {
       node.getBlockData.mockImplementation(param =>
-        Promise.resolve(param === 'proven' ? blockAtCheckpoint(5) : blockAtCheckpoint(7)),
+        Promise.resolve(param === 'proven' ? blockWithMessageLeaves(6) : blockWithMessageLeaves(8)),
       );
 
       expect(await isL1ToL2MessageReady(node, messageHash, 'proven')).toBe(true);

yarn-project/aztec.js/src/utils/cross_chain.ts

@@ -10,7 +10,7 @@ import type { AztecNode } from '@aztec/stdlib/interfaces/client';
  * @param opts - Options
  */
 export function waitForL1ToL2MessageReady(
-  node: Pick<AztecNode, 'getBlockData' | 'getL1ToL2MessageCheckpoint'>,
+  node: Pick<AztecNode, 'getBlockData' | 'getL1ToL2MessageIndex'>,
   l1ToL2MessageHash: Fr,
   opts: {
     /** Timeout for the operation in seconds */ timeoutSeconds: number;
@@ -39,16 +39,17 @@ export function waitForL1ToL2MessageReady(
  * @returns True if the message is ready to be consumed, false otherwise
  */
 export async function isL1ToL2MessageReady(
-  node: Pick<AztecNode, 'getBlockData' | 'getL1ToL2MessageCheckpoint'>,
+  node: Pick<AztecNode, 'getBlockData' | 'getL1ToL2MessageIndex'>,
   l1ToL2MessageHash: Fr,
   chainTip: BlockTag = 'latest',
 ): Promise<boolean> {
-  const messageCheckpointNumber = await node.getL1ToL2MessageCheckpoint(l1ToL2MessageHash);
-  if (messageCheckpointNumber === undefined) {
+  const messageIndex = await node.getL1ToL2MessageIndex(l1ToL2MessageHash);
+  if (messageIndex === undefined) {
     return false;
   }
 
-  // L1 to L2 messages are included in the first block of a checkpoint
+  // Blocks consume L1-to-L2 messages in Inbox order into consecutive leaves of the message tree, so the message is
+  // available at a tip exactly when that tip's tree has grown past the message's leaf index.
   const block = await node.getBlockData(chainTip);
-  return block !== undefined && block.checkpointNumber >= messageCheckpointNumber;
+  return block !== undefined && messageIndex < BigInt(block.header.state.l1ToL2MessageTree.nextAvailableLeafIndex);
 }

yarn-project/end-to-end/src/bench/node_rpc_perf.test.ts

@@ -434,12 +434,10 @@ describe('e2e_node_rpc_perf', () => {
   });
 
   describe('message APIs', () => {
-    it('benchmarks getL1ToL2MessageCheckpoint', async () => {
+    it('benchmarks getL1ToL2MessageIndex', async () => {
       const l1ToL2Message = Fr.random();
-      const { stats } = await benchmark('getL1ToL2MessageCheckpoint', () =>
-        aztecNode.getL1ToL2MessageCheckpoint(l1ToL2Message),
-      );
-      addResult('getL1ToL2MessageCheckpoint', stats);
+      const { stats } = await benchmark('getL1ToL2MessageIndex', () => aztecNode.getL1ToL2MessageIndex(l1ToL2Message));
+      addResult('getL1ToL2MessageIndex', stats);
       expect(stats.avg).toBeLessThan(2000);
     });
 

yarn-project/end-to-end/src/single-node/cross-chain/message_test_helpers.ts

@@ -4,7 +4,7 @@ import type { Logger } from '@aztec/aztec.js/log';
 import { isL1ToL2MessageReady } from '@aztec/aztec.js/messaging';
 import type { AztecNode } from '@aztec/aztec.js/node';
 import type { Wallet } from '@aztec/aztec.js/wallet';
-import type { BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
+import type { BlockNumber } from '@aztec/foundation/branded-types';
 import { retryUntil } from '@aztec/foundation/retry';
 import { ExecutionPayload } from '@aztec/stdlib/tx';
 
@@ -33,7 +33,7 @@ export interface L1ToL2MessageHelpers {
     secretHash: Fr;
   }): ReturnType<typeof sendL1ToL2Message>;
   advanceBlock(): Promise<BlockNumber>;
-  waitForMessageFetched(msgHash: Fr): Promise<CheckpointNumber>;
+  waitForMessageIndexed(msgHash: Fr): Promise<bigint>;
   waitForMessageReady(
     msgHash: Fr,
     scope: L1ToL2MessageScope,
@@ -72,20 +72,20 @@ export function createL1ToL2MessageHelpers(deps: L1ToL2MessageHelperDeps): L1ToL
     return newBlock;
   };
 
-  // Waits until the message is fetched by the archiver of the node and returns the msg target checkpoint.
-  // Advances a block on each retry because an L1->L2 message is only indexed once further L2 blocks build.
-  const waitForMessageFetched = async (msgHash: Fr) => {
+  // Waits until the node's archiver has ingested the message from the Inbox and returns its message-tree leaf index.
+  // Advances a block on each retry to keep the chain moving while the archiver catches up with L1.
+  const waitForMessageIndexed = async (msgHash: Fr) => {
     log.warn(`Waiting until the message is fetched by the node`);
     return await retryUntil(
       async () => {
-        const checkpoint = await aztecNode.getL1ToL2MessageCheckpoint(msgHash);
-        if (checkpoint !== undefined) {
-          return checkpoint;
+        const messageIndex = await aztecNode.getL1ToL2MessageIndex(msgHash);
+        if (messageIndex !== undefined) {
+          return messageIndex;
         }
         await advanceBlock();
         return undefined;
       },
-      'get msg checkpoint',
+      'get msg index',
       60,
     );
   };
@@ -96,9 +96,9 @@ export function createL1ToL2MessageHelpers(deps: L1ToL2MessageHelperDeps): L1ToL
     scope: L1ToL2MessageScope,
     onNotReady?: (blockNumber: BlockNumber) => Promise<void>,
   ) => {
-    const msgCheckpoint = await waitForMessageFetched(msgHash);
+    const msgIndex = await waitForMessageIndexed(msgHash);
     log.warn(
-      `Waiting until L2 reaches the first block of msg checkpoint ${msgCheckpoint} (current is ${await aztecNode.getCheckpointNumber()})`,
+      `Waiting until L2 consumes msg leaf index ${msgIndex} (checkpoint is ${await aztecNode.getCheckpointNumber()})`,
     );
     await retryUntil(
       async () => {
@@ -109,17 +109,17 @@ export function createL1ToL2MessageHelpers(deps: L1ToL2MessageHelperDeps): L1ToL
         const witness = await aztecNode.getL1ToL2MessageMembershipWitness('latest', msgHash);
         const isReady = await isL1ToL2MessageReady(aztecNode, msgHash, t.pxeSyncChainTip);
         log.info(
-          `Block is ${blockNumber}, checkpoint is ${checkpointNumber}. Message checkpoint is ${msgCheckpoint}. Witness ${!!witness}. Ready ${isReady}.`,
+          `Block is ${blockNumber}, checkpoint is ${checkpointNumber}. Message leaf index is ${msgIndex}. Witness ${!!witness}. Ready ${isReady}.`,
         );
         if (!isReady) {
           await (onNotReady ? onNotReady(blockNumber) : advanceBlock());
         }
         return isReady;
       },
-      `wait for rollup to reach msg checkpoint ${msgCheckpoint}`,
+      `wait for rollup to consume msg leaf index ${msgIndex}`,
       240,
     );
   };
 
-  return { sendMessageToL2, advanceBlock, waitForMessageFetched, waitForMessageReady };
+  return { sendMessageToL2, advanceBlock, waitForMessageIndexed, waitForMessageReady };
 }

yarn-project/stdlib/src/interfaces/aztec-node.test.ts

@@ -154,11 +154,6 @@ describe('AztecNodeApiSchema', () => {
     expect(response).toEqual([1n, expect.any(SiblingPath)]);
   });
 
-  it('getL1ToL2MessageCheckpoint', async () => {
-    const response = await context.client.getL1ToL2MessageCheckpoint(Fr.random());
-    expect(response).toEqual(5);
-  });
-
   it('getL1ToL2MessageIndex', async () => {
     const response = await context.client.getL1ToL2MessageIndex(Fr.random());
     expect(response).toEqual(5n);
@@ -715,10 +710,6 @@ class MockAztecNode implements AztecNode {
     expect(noteHash).toBeInstanceOf(Fr);
     return Promise.resolve(MembershipWitness.random(NOTE_HASH_TREE_HEIGHT));
   }
-  getL1ToL2MessageCheckpoint(l1ToL2Message: Fr): Promise<CheckpointNumber | undefined> {
-    expect(l1ToL2Message).toBeInstanceOf(Fr);
-    return Promise.resolve(CheckpointNumber(5));
-  }
   getL1ToL2MessageIndex(l1ToL2Message: Fr): Promise<bigint | undefined> {
     expect(l1ToL2Message).toBeInstanceOf(Fr);
     return Promise.resolve(5n);