fix(bot): check L1-to-L2 message readiness against PXE sync tip (#24004)

## Motivation

The bot waits for its Fee Juice bridge claim with
`waitForL1ToL2MessageReady` and then immediately simulates the account
deployment that consumes the claim. Readiness was always evaluated
against the `latest` block, but the bot's embedded PXE can be configured
to sync to a slower tip (e.g. `syncChainTip=checkpointed`). When the
tips diverge, readiness passes while the PXE simulation anchors to an
older block whose message tree does not contain the message yet, and
simulation fails with `No L1 to L2 message found for message hash ...`,
sending the bot into a crash loop where it repeatedly validates a claim
it cannot consume.

## Approach

Make readiness answer the question the consumer actually needs: is the
message present at the same chain tip the consuming PXE will anchor its
simulation to?

- `isL1ToL2MessageReady` / `waitForL1ToL2MessageReady` accept an
optional chain tip (`BlockTag`), defaulting to `latest` so existing
callers are unaffected. The helper compares the message checkpoint
against the block at the requested tip.
- The bot does not get a new config knob and no wallet APIs change:
`addBot` extracts `syncChainTip` from the same PXE options its callers
use to build the embedded wallet, and threads it through `BotRunner` →
bot `create` → `BotFactory`. This keeps the readiness tip from drifting
from the PXE's actual config. Polling the node at the PXE's configured
tip (rather than exposing the PXE anchor) is required for the wait to
make progress, since the PXE synchronizer is pull-on-demand and its
anchor only advances on `pxe.sync()`.
- All bot readiness checks now pass the tip: the stored-claim
revalidation and the new-claim wait in `BotFactory`, the cross-chain
setup wait, and the steady-state message selection in `CrossChainBot`.

## API changes

`isL1ToL2MessageReady(node, msgHash, chainTip?)` and
`waitForL1ToL2MessageReady(node, msgHash, { timeoutSeconds, chainTip?
})` in `@aztec/aztec.js/messaging` accept an optional `BlockTag`
(default `'latest'`, preserving previous behavior). Their node
dependency narrowed from `getBlock` to the cheaper `getBlockData`.

## Changes

- **aztec.js**: tip-aware readiness helpers in `utils/cross_chain.ts`;
new unit tests covering the latest fallback and the tip-aware path.
- **bot**: `BotRunner`, `Bot`/`AmmBot`/`CrossChainBot.create`, and
`BotFactory` accept the PXE sync tip and use it at every L1-to-L2
readiness check.
- **aztec**: `addBot` extracts `syncChainTip` from the PXE options and
passes it to `BotRunner`.

Fixes A-1155

Author: spalladino

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

@@ -0,0 +1,84 @@
+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';
+
+import { type MockProxy, mock } from 'jest-mock-extended';
+
+import { isL1ToL2MessageReady } from './cross_chain.js';
+
+describe('isL1ToL2MessageReady', () => {
+  let node: MockProxy<Pick<AztecNode, 'getBlockData' | 'getL1ToL2MessageCheckpoint'>>;
+  let messageHash: Fr;
+
+  const blockAtCheckpoint = (checkpointNumber: number) =>
+    ({ checkpointNumber: CheckpointNumber(checkpointNumber) }) 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);
+
+    expect(await isL1ToL2MessageReady(node, messageHash)).toBe(false);
+    expect(node.getBlockData).not.toHaveBeenCalled();
+  });
+
+  describe('latest fallback (no chain tip)', () => {
+    beforeEach(() => {
+      node.getL1ToL2MessageCheckpoint.mockResolvedValue(CheckpointNumber(5));
+    });
+
+    it('checks readiness against the latest block', async () => {
+      node.getBlockData.mockResolvedValue(blockAtCheckpoint(5));
+
+      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));
+
+      expect(await isL1ToL2MessageReady(node, messageHash)).toBe(true);
+    });
+
+    it('returns false when the latest block is behind the message checkpoint', async () => {
+      node.getBlockData.mockResolvedValue(blockAtCheckpoint(4));
+
+      expect(await isL1ToL2MessageReady(node, messageHash)).toBe(false);
+    });
+
+    it('returns false when there is no block', async () => {
+      node.getBlockData.mockResolvedValue(undefined);
+
+      expect(await isL1ToL2MessageReady(node, messageHash)).toBe(false);
+    });
+  });
+
+  describe('with an explicit chain tip', () => {
+    beforeEach(() => {
+      node.getL1ToL2MessageCheckpoint.mockResolvedValue(CheckpointNumber(5));
+    });
+
+    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.
+      node.getBlockData.mockImplementation(param =>
+        Promise.resolve(param === 'proven' ? blockAtCheckpoint(4) : blockAtCheckpoint(6)),
+      );
+
+      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 () => {
+      node.getBlockData.mockImplementation(param =>
+        Promise.resolve(param === 'proven' ? blockAtCheckpoint(5) : blockAtCheckpoint(7)),
+      );
+
+      expect(await isL1ToL2MessageReady(node, messageHash, 'proven')).toBe(true);
+    });
+  });
+});

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

@@ -1,5 +1,6 @@
 import type { Fr } from '@aztec/foundation/curves/bn254';
 import { retryUntil } from '@aztec/foundation/retry';
+import type { BlockTag } from '@aztec/stdlib/block';
 import type { AztecNode } from '@aztec/stdlib/interfaces/client';
 
 /**
@@ -9,14 +10,20 @@ import type { AztecNode } from '@aztec/stdlib/interfaces/client';
  * @param opts - Options
  */
 export function waitForL1ToL2MessageReady(
-  node: Pick<AztecNode, 'getBlock' | 'getL1ToL2MessageCheckpoint'>,
+  node: Pick<AztecNode, 'getBlockData' | 'getL1ToL2MessageCheckpoint'>,
   l1ToL2MessageHash: Fr,
   opts: {
     /** Timeout for the operation in seconds */ timeoutSeconds: number;
+    /**
+     * Chain tip to evaluate readiness against. Defaults to `'latest'`. Set this to the tip the consuming PXE syncs to
+     * (e.g. `'proven'`) so readiness answers whether the message is present at the same block the transaction
+     * simulation will anchor to, not at a newer tip.
+     */
+    chainTip?: BlockTag;
   },
 ) {
   return retryUntil(
-    () => isL1ToL2MessageReady(node, l1ToL2MessageHash),
+    () => isL1ToL2MessageReady(node, l1ToL2MessageHash, opts.chainTip),
     `L1 to L2 message ${l1ToL2MessageHash.toString()} ready`,
     opts.timeoutSeconds,
     1,
@@ -27,18 +34,21 @@ export function waitForL1ToL2MessageReady(
  * Returns whether the L1 to L2 message is ready to be consumed.
  * @param node - Aztec node instance used to obtain the information about the message
  * @param l1ToL2MessageHash - Hash of the L1 to L2 message
+ * @param chainTip - Chain tip to evaluate readiness against. Defaults to `'latest'`. Pass the tip the consuming PXE
+ * syncs to (e.g. `'proven'`) so readiness is checked at the block the transaction simulation will anchor to.
  * @returns True if the message is ready to be consumed, false otherwise
  */
 export async function isL1ToL2MessageReady(
-  node: Pick<AztecNode, 'getBlock' | 'getL1ToL2MessageCheckpoint'>,
+  node: Pick<AztecNode, 'getBlockData' | 'getL1ToL2MessageCheckpoint'>,
   l1ToL2MessageHash: Fr,
+  chainTip: BlockTag = 'latest',
 ): Promise<boolean> {
   const messageCheckpointNumber = await node.getL1ToL2MessageCheckpoint(l1ToL2MessageHash);
   if (messageCheckpointNumber === undefined) {
     return false;
   }
 
   // L1 to L2 messages are included in the first block of a checkpoint
-  const latestBlock = await node.getBlock('latest');
-  return latestBlock !== undefined && latestBlock.checkpointNumber >= messageCheckpointNumber;
+  const block = await node.getBlockData(chainTip);
+  return block !== undefined && block.checkpointNumber >= messageCheckpointNumber;
 }

yarn-project/aztec/src/cli/cmds/start_bot.ts

@@ -56,14 +56,19 @@ export async function addBot(
   const config = extractRelevantOptions<BotConfig>(options, botConfigMappings, 'bot');
   userLog?.(`Starting bot with config ${stringifyConfig(config)}`);
 
+  // The bot wallet's embedded PXE syncs to this tip (see start_bot.ts/start_node.ts which build the wallet from the
+  // same options). L1-to-L2 readiness checks must be evaluated at this tip rather than at 'latest', or the bot can
+  // consider a message ready while the PXE simulation anchors to an older block that cannot prove its membership yet.
+  const { syncChainTip } = extractRelevantOptions<PXEConfig & CliPXEOptions>(options, allPxeConfigMappings, 'pxe');
+
   const db = await (config.dataDirectory
     ? createStore('bot', BotStore.SCHEMA_VERSION, config)
     : openTmpStore('bot', true, config.dataStoreMapSizeKb));
 
   const store = new BotStore(db);
   await store.cleanupOldClaims();
 
-  const botRunner = new BotRunner(config, wallet, aztecNode, telemetry, aztecNodeAdmin, store);
+  const botRunner = new BotRunner(config, wallet, aztecNode, telemetry, aztecNodeAdmin, store, syncChainTip);
   if (!config.noStart) {
     void botRunner.start(); // Do not block since bot setup takes time
   }

yarn-project/bot/src/amm_bot.ts

@@ -5,6 +5,7 @@ import type { TxHash, TxReceipt } from '@aztec/aztec.js/tx';
 import { jsonStringify } from '@aztec/foundation/json-rpc';
 import type { AMMContract } from '@aztec/noir-contracts.js/AMM';
 import type { TokenContract } from '@aztec/noir-contracts.js/Token';
+import type { BlockTag } from '@aztec/stdlib/block';
 import type { AztecNode, AztecNodeAdmin } from '@aztec/stdlib/interfaces/client';
 import type { EmbeddedWallet } from '@aztec/wallets/embedded';
 
@@ -37,13 +38,15 @@ export class AmmBot extends BaseBot {
     aztecNode: AztecNode,
     aztecNodeAdmin: AztecNodeAdmin | undefined,
     store: BotStore,
+    syncChainTip?: BlockTag,
   ): Promise<AmmBot> {
     const { defaultAccountAddress, token0, token1, amm } = await new BotFactory(
       config,
       wallet,
       store,
       aztecNode,
       aztecNodeAdmin,
+      syncChainTip,
     ).setupAmm();
     return new AmmBot(aztecNode, wallet, defaultAccountAddress, amm, token0, token1, config);
   }

yarn-project/bot/src/bot.ts

@@ -4,6 +4,7 @@ import { TxHash } from '@aztec/aztec.js/tx';
 import { times } from '@aztec/foundation/collection';
 import type { PrivateTokenContract } from '@aztec/noir-contracts.js/PrivateToken';
 import type { TokenContract } from '@aztec/noir-contracts.js/Token';
+import type { BlockTag } from '@aztec/stdlib/block';
 import type { AztecNode, AztecNodeAdmin } from '@aztec/stdlib/interfaces/client';
 import type { EmbeddedWallet } from '@aztec/wallets/embedded';
 
@@ -33,13 +34,15 @@ export class Bot extends BaseBot {
     aztecNode: AztecNode,
     aztecNodeAdmin: AztecNodeAdmin | undefined,
     store: BotStore,
+    syncChainTip?: BlockTag,
   ): Promise<Bot> {
     const { defaultAccountAddress, token, recipient } = await new BotFactory(
       config,
       wallet,
       store,
       aztecNode,
       aztecNodeAdmin,
+      syncChainTip,
     ).setup();
     return new Bot(aztecNode, wallet, defaultAccountAddress, token, recipient, config);
   }

yarn-project/bot/src/cross_chain_bot.ts

@@ -31,6 +31,7 @@ import type { ExtendedViemWalletClient } from '@aztec/ethereum/types';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import type { TestContract } from '@aztec/noir-test-contracts.js/Test';
+import type { BlockTag } from '@aztec/stdlib/block';
 import type { AztecNode, AztecNodeAdmin } from '@aztec/stdlib/interfaces/client';
 import type { EmbeddedWallet } from '@aztec/wallets/embedded';
 
@@ -60,6 +61,7 @@ export class CrossChainBot extends BaseBot {
     private readonly rollupVersion: bigint,
     private readonly store: BotStore,
     config: BotConfig,
+    private readonly syncChainTip?: BlockTag,
   ) {
     super(node, wallet, defaultAccountAddress, config);
   }
@@ -70,11 +72,12 @@ export class CrossChainBot extends BaseBot {
     aztecNode: AztecNode,
     aztecNodeAdmin: AztecNodeAdmin | undefined,
     store: BotStore,
+    syncChainTip?: BlockTag,
   ): Promise<CrossChainBot> {
     if (config.followChain === 'NONE') {
       throw new Error(`CrossChainBot requires followChain to be set (got NONE)`);
     }
-    const factory = new BotFactory(config, wallet, store, aztecNode, aztecNodeAdmin);
+    const factory = new BotFactory(config, wallet, store, aztecNode, aztecNodeAdmin, syncChainTip);
     const { defaultAccountAddress, contract, l1Client, rollupVersion } = await factory.setupCrossChain();
     const l1Recipient = EthAddress.fromString(l1Client.account!.address);
     const { l1ContractAddresses } = await aztecNode.getNodeInfo();
@@ -90,6 +93,7 @@ export class CrossChainBot extends BaseBot {
       rollupVersion,
       store,
       config,
+      syncChainTip,
     );
   }
 
@@ -176,7 +180,7 @@ export class CrossChainBot extends BaseBot {
   ): Promise<PendingL1ToL2Message | undefined> {
     const now = Date.now();
     for (const msg of pendingMessages) {
-      const ready = await isL1ToL2MessageReady(this.node, Fr.fromHexString(msg.msgHash));
+      const ready = await isL1ToL2MessageReady(this.node, Fr.fromHexString(msg.msgHash), this.syncChainTip);
       if (ready) {
         return msg;
       }

yarn-project/bot/src/factory.ts

@@ -29,6 +29,7 @@ import { AMMContract } from '@aztec/noir-contracts.js/AMM';
 import { PrivateTokenContract } from '@aztec/noir-contracts.js/PrivateToken';
 import { TokenContract } from '@aztec/noir-contracts.js/Token';
 import { TestContract } from '@aztec/noir-test-contracts.js/Test';
+import type { BlockTag } from '@aztec/stdlib/block';
 import type { ContractInstanceWithAddress } from '@aztec/stdlib/contract';
 import { GasFees, ManaUsageEstimate } from '@aztec/stdlib/gas';
 import type { AztecNode, AztecNodeAdmin } from '@aztec/stdlib/interfaces/client';
@@ -54,6 +55,7 @@ export class BotFactory {
     private readonly store: BotStore,
     private readonly aztecNode: AztecNode,
     private readonly aztecNodeAdmin?: AztecNodeAdmin,
+    private readonly syncChainTip?: BlockTag,
   ) {
     // Set fee padding on the wallet so that all transactions during setup
     // (token deploy, minting, etc.) use the configured padding, not the default.
@@ -174,6 +176,7 @@ export class BotFactory {
       const firstMsg = allMessages[0];
       await waitForL1ToL2MessageReady(this.aztecNode, Fr.fromHexString(firstMsg.msgHash), {
         timeoutSeconds: this.config.l1ToL2MessageTimeoutSeconds,
+        chainTip: this.syncChainTip,
       });
       this.log.info(`First L1→L2 message is ready`);
     }
@@ -675,6 +678,7 @@ export class BotFactory {
         await this.withNoMinTxsPerBlock(() =>
           waitForL1ToL2MessageReady(this.aztecNode, messageHash, {
             timeoutSeconds: this.config.l1ToL2MessageTimeoutSeconds,
+            chainTip: this.syncChainTip,
           }),
         );
         return existingClaim.claim;
@@ -713,6 +717,7 @@ export class BotFactory {
     await this.withNoMinTxsPerBlock(() =>
       waitForL1ToL2MessageReady(this.aztecNode, Fr.fromHexString(claim.messageHash), {
         timeoutSeconds: this.config.l1ToL2MessageTimeoutSeconds,
+        chainTip: this.syncChainTip,
       }),
     );
 

yarn-project/bot/src/runner.ts

@@ -2,6 +2,7 @@ import { createLogger } from '@aztec/aztec.js/log';
 import type { AztecNode } from '@aztec/aztec.js/node';
 import { omit } from '@aztec/foundation/collection';
 import { RunningPromise } from '@aztec/foundation/running-promise';
+import type { BlockTag } from '@aztec/stdlib/block';
 import type { AztecNodeAdmin } from '@aztec/stdlib/interfaces/client';
 import { type TelemetryClient, type Traceable, type Tracer, trackSpan } from '@aztec/telemetry-client';
 import type { EmbeddedWallet } from '@aztec/wallets/embedded';
@@ -30,6 +31,7 @@ export class BotRunner implements BotRunnerApi, Traceable {
     private readonly telemetry: TelemetryClient,
     private readonly aztecNodeAdmin: AztecNodeAdmin | undefined,
     private readonly store: BotStore,
+    private readonly syncChainTip?: BlockTag,
   ) {
     this.tracer = telemetry.getTracer('Bot');
 
@@ -149,13 +151,34 @@ export class BotRunner implements BotRunnerApi, Traceable {
     try {
       switch (this.config.botMode) {
         case 'crosschain':
-          this.bot = CrossChainBot.create(this.config, this.wallet, this.aztecNode, this.aztecNodeAdmin, this.store);
+          this.bot = CrossChainBot.create(
+            this.config,
+            this.wallet,
+            this.aztecNode,
+            this.aztecNodeAdmin,
+            this.store,
+            this.syncChainTip,
+          );
           break;
         case 'amm':
-          this.bot = AmmBot.create(this.config, this.wallet, this.aztecNode, this.aztecNodeAdmin, this.store);
+          this.bot = AmmBot.create(
+            this.config,
+            this.wallet,
+            this.aztecNode,
+            this.aztecNodeAdmin,
+            this.store,
+            this.syncChainTip,
+          );
           break;
         case 'transfer':
-          this.bot = Bot.create(this.config, this.wallet, this.aztecNode, this.aztecNodeAdmin, this.store);
+          this.bot = Bot.create(
+            this.config,
+            this.wallet,
+            this.aztecNode,
+            this.aztecNodeAdmin,
+            this.store,
+            this.syncChainTip,
+          );
           break;
         default: {
           const _exhaustive: never = this.config.botMode;