@aztec-labs/bot 6.0.0-nightly.20260829

package/src/config.ts

@@ -0,0 +1,316 @@
+import {
+  type ConfigMappingsType,
+  SecretValue,
+  booleanConfigHelper,
+  floatConfigHelper,
+  getConfigFromMappings,
+  getDefaultConfig,
+  numberConfigHelper,
+  optionalNumberConfigHelper,
+  pickConfigMappings,
+  secretFrConfigHelper,
+  secretStringConfigHelper,
+} from '@aztec-labs/foundation/config';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { getVKTreeRoot } from '@aztec-labs/noir-protocol-circuits-types/vk-tree';
+import { protocolContractsHash } from '@aztec-labs/protocol-contracts';
+import { type DataStoreConfig, dataConfigMappings } from '@aztec-labs/stdlib/kv-store';
+import { schemas, zodFor } from '@aztec-labs/stdlib/schemas';
+import type { ComponentsVersions } from '@aztec-labs/stdlib/versioning';
+import { z } from 'zod';
+
+const BotFollowChain = ['NONE', 'PROPOSED', 'CHECKPOINTED', 'PROVEN'] as const;
+type BotFollowChain = (typeof BotFollowChain)[number];
+
+const BotMode = ['transfer', 'amm', 'crosschain'] as const;
+type BotMode = (typeof BotMode)[number];
+
+export enum SupportedTokenContracts {
+  TokenContract = 'TokenContract',
+  PrivateTokenContract = 'PrivateTokenContract',
+}
+
+export type BotConfig = {
+  /** The URL to the Aztec node to check for tx pool status. */
+  nodeUrl: string | undefined;
+  /** The URL to the Aztec node admin API to force-flush txs if configured. */
+  nodeAdminUrl: string | undefined;
+  /** Url of the ethereum host. */
+  l1RpcUrls: string[] | undefined;
+  /** The mnemonic for the account to bridge fee juice from L1. */
+  l1Mnemonic: SecretValue<string> | undefined;
+  /** The private key for the account to bridge fee juice from L1. */
+  l1PrivateKey: SecretValue<string> | undefined;
+  /** How long to wait for L1 to L2 messages to become available on L2 */
+  l1ToL2MessageTimeoutSeconds: number;
+  /** Signing private key for the sender account. */
+  senderPrivateKey: SecretValue<Fr> | undefined;
+  /** Optional salt to use to instantiate the sender account */
+  senderSalt: Fr | undefined;
+  /** Salt for the token contract instantiation. */
+  tokenSalt: Fr;
+  /** Every how many seconds should a new tx be sent. */
+  txIntervalSeconds: number;
+  /** How many private token transfers are executed per tx. */
+  privateTransfersPerTx: number;
+  /** How many public token transfers are executed per tx. */
+  publicTransfersPerTx: number;
+  /** How to handle fee payments. */
+  feePaymentMethod: 'fee_juice';
+  /** 'How much is the bot willing to overpay vs. the current min fee' */
+  minFeePadding: number;
+  /** True to not automatically setup or start the bot on initialization. */
+  noStart: boolean;
+  /** How long to wait for a tx to be mined before reporting an error. */
+  txMinedWaitSeconds: number;
+  /** Whether to wait for txs to be proven, to be mined, or no wait at all. */
+  followChain: BotFollowChain;
+  /** Do not send a tx if the node's tx pool already has this many pending txs. */
+  maxPendingTxs: number;
+  /** Whether to flush after sending each 'setup' transaction */
+  flushSetupTransactions: boolean;
+  /** L2 gas limit for the tx (empty to let the bot's wallet estimate). */
+  l2GasLimit: number | undefined;
+  /** DA gas limit for the tx (empty to let the bot's wallet estimate). */
+  daGasLimit: number | undefined;
+  /** Token contract to use */
+  contract: SupportedTokenContracts;
+  /** The maximum number of consecutive errors before the bot shuts down */
+  maxConsecutiveErrors: number;
+  /** Stops the bot if service becomes unhealthy */
+  stopWhenUnhealthy: boolean;
+  /** Bot mode: transfer, amm, or crosschain. */
+  botMode: BotMode;
+  /** Number of L2→L1 messages per tx (crosschain mode). */
+  l2ToL1MessagesPerTx: number;
+  /** Max L1→L2 messages to keep in-flight (crosschain mode). */
+  l1ToL2SeedCount: number;
+} & Pick<DataStoreConfig, 'dataDirectory' | 'dataStoreMapSizeKb'>;
+
+export const BotConfigSchema = zodFor<BotConfig>()(
+  z
+    .object({
+      nodeUrl: z.string().optional(),
+      nodeAdminUrl: z.string().optional(),
+      l1RpcUrls: z.array(z.string()).optional(),
+      l1Mnemonic: schemas.SecretValue(z.string()).optional(),
+      l1PrivateKey: schemas.SecretValue(z.string()).optional(),
+      l1ToL2MessageTimeoutSeconds: z.number(),
+      senderPrivateKey: schemas.SecretValue(schemas.Fr).optional(),
+      senderSalt: schemas.Fr.optional(),
+      tokenSalt: schemas.Fr,
+      txIntervalSeconds: z.number(),
+      privateTransfersPerTx: z.number().int().nonnegative(),
+      publicTransfersPerTx: z.number().int().nonnegative(),
+      feePaymentMethod: z.literal('fee_juice'),
+      minFeePadding: z.number().nonnegative(),
+      noStart: z.boolean(),
+      txMinedWaitSeconds: z.number(),
+      followChain: z.enum(BotFollowChain),
+      maxPendingTxs: z.number().int().nonnegative(),
+      flushSetupTransactions: z.boolean(),
+      l2GasLimit: z.number().int().nonnegative().optional(),
+      daGasLimit: z.number().int().nonnegative().optional(),
+      contract: z.nativeEnum(SupportedTokenContracts),
+      maxConsecutiveErrors: z.number().int().nonnegative(),
+      stopWhenUnhealthy: z.boolean(),
+      botMode: z.enum(BotMode).default('transfer'),
+      l2ToL1MessagesPerTx: z.number().int().nonnegative().default(1),
+      l1ToL2SeedCount: z.number().int().nonnegative().default(1),
+      dataDirectory: z.string().optional(),
+      dataStoreMapSizeKb: z.number().optional(),
+    })
+    .transform(config => ({
+      nodeUrl: undefined,
+      nodeAdminUrl: undefined,
+      l1RpcUrls: undefined,
+      senderSalt: undefined,
+      l2GasLimit: undefined,
+      daGasLimit: undefined,
+      l1Mnemonic: undefined,
+      l1PrivateKey: undefined,
+      senderPrivateKey: undefined,
+      dataStoreMapSizeKb: 1_024 * 1_024,
+      ...config,
+    })),
+);
+
+export const botConfigMappings: ConfigMappingsType<BotConfig> = {
+  nodeUrl: {
+    env: 'AZTEC_NODE_URL',
+    description: 'The URL to the Aztec node to check for tx pool status.',
+  },
+  nodeAdminUrl: {
+    env: 'AZTEC_NODE_ADMIN_URL',
+    description: 'The URL to the Aztec node admin API to force-flush txs if configured.',
+  },
+  l1RpcUrls: {
+    env: 'ETHEREUM_HOSTS',
+    description: 'URL of the ethereum host.',
+    parseEnv: (val: string) => val.split(',').map(url => url.trim()),
+  },
+  l1Mnemonic: {
+    env: 'BOT_L1_MNEMONIC',
+    description: 'The mnemonic for the account to bridge fee juice from L1.',
+    ...secretStringConfigHelper(),
+  },
+  l1PrivateKey: {
+    env: 'BOT_L1_PRIVATE_KEY',
+    description: 'The private key for the account to bridge fee juice from L1.',
+    ...secretStringConfigHelper(),
+  },
+  l1ToL2MessageTimeoutSeconds: {
+    env: 'BOT_L1_TO_L2_TIMEOUT_SECONDS',
+    description: 'How long to wait for L1 to L2 messages to become available on L2',
+    ...numberConfigHelper(3600),
+  },
+  senderPrivateKey: {
+    env: 'BOT_PRIVATE_KEY',
+    description: 'Signing private key for the sender account.',
+    ...secretFrConfigHelper(),
+  },
+  senderSalt: {
+    env: 'BOT_ACCOUNT_SALT',
+    description: 'The salt to use to deploy the sender account.',
+    parseEnv: (val: string) => (val ? Fr.fromHexString(val) : undefined),
+  },
+  tokenSalt: {
+    env: 'BOT_TOKEN_SALT',
+    description: 'The salt to use to deploy the token contract.',
+    parseEnv: (val: string) => Fr.fromHexString(val),
+    defaultValue: Fr.fromHexString('1'),
+  },
+  txIntervalSeconds: {
+    env: 'BOT_TX_INTERVAL_SECONDS',
+    description: 'Every how many seconds should a new tx be sent.',
+    ...numberConfigHelper(60),
+  },
+  privateTransfersPerTx: {
+    env: 'BOT_PRIVATE_TRANSFERS_PER_TX',
+    description: 'How many private token transfers are executed per tx.',
+    ...numberConfigHelper(1),
+  },
+  publicTransfersPerTx: {
+    env: 'BOT_PUBLIC_TRANSFERS_PER_TX',
+    description: 'How many public token transfers are executed per tx.',
+    ...numberConfigHelper(1),
+  },
+  feePaymentMethod: {
+    env: 'BOT_FEE_PAYMENT_METHOD',
+    description: 'How to handle fee payments. (Options: fee_juice)',
+    parseEnv: val => (val as 'fee_juice') || undefined,
+    defaultValue: 'fee_juice',
+  },
+  minFeePadding: {
+    env: 'BOT_MIN_FEE_PADDING',
+    description: 'How much is the bot willing to overpay vs. the current base fee',
+    ...floatConfigHelper(3),
+  },
+  noStart: {
+    env: 'BOT_NO_START',
+    description: 'True to not automatically setup or start the bot on initialization.',
+    ...booleanConfigHelper(),
+  },
+  txMinedWaitSeconds: {
+    env: 'BOT_TX_MINED_WAIT_SECONDS',
+    description: 'How long to wait for a tx to be mined before reporting an error.',
+    ...numberConfigHelper(180),
+  },
+  followChain: {
+    env: 'BOT_FOLLOW_CHAIN',
+    description: 'Which chain the bot follows',
+    defaultValue: 'NONE',
+    parseEnv(val) {
+      const upper = val.toUpperCase();
+      if (upper === 'PENDING') {
+        return 'CHECKPOINTED';
+      }
+      if (!(BotFollowChain as readonly string[]).includes(upper)) {
+        throw new Error(`Invalid value for BOT_FOLLOW_CHAIN: ${val}`);
+      }
+      return upper as BotFollowChain;
+    },
+  },
+  maxPendingTxs: {
+    env: 'BOT_MAX_PENDING_TXS',
+    description: "Do not send a tx if the node's tx pool already has this many pending txs.",
+    ...numberConfigHelper(128),
+  },
+  flushSetupTransactions: {
+    env: 'BOT_FLUSH_SETUP_TRANSACTIONS',
+    description: 'Make a request for the sequencer to build a block after each setup transaction.',
+    ...booleanConfigHelper(false),
+  },
+  l2GasLimit: {
+    env: 'BOT_L2_GAS_LIMIT',
+    description: "L2 gas limit for the tx (empty to let the bot's wallet estimate).",
+    ...optionalNumberConfigHelper(),
+  },
+  daGasLimit: {
+    env: 'BOT_DA_GAS_LIMIT',
+    description: "DA gas limit for the tx (empty to let the bot's wallet estimate).",
+    ...optionalNumberConfigHelper(),
+  },
+  contract: {
+    env: 'BOT_TOKEN_CONTRACT',
+    description: 'Token contract to use',
+    defaultValue: SupportedTokenContracts.TokenContract,
+    parseEnv(val) {
+      if (!Object.values(SupportedTokenContracts).includes(val as any)) {
+        throw new Error(
+          `Invalid value for BOT_TOKEN_CONTRACT: ${val}. Valid values: ${Object.values(SupportedTokenContracts).join(
+            ', ',
+          )}`,
+        );
+      }
+      return val as SupportedTokenContracts;
+    },
+  },
+  maxConsecutiveErrors: {
+    env: 'BOT_MAX_CONSECUTIVE_ERRORS',
+    description: 'The maximum number of consecutive errors before the bot shuts down',
+    ...numberConfigHelper(0),
+  },
+  stopWhenUnhealthy: {
+    env: 'BOT_STOP_WHEN_UNHEALTHY',
+    description: 'Stops the bot if service becomes unhealthy',
+    ...booleanConfigHelper(false),
+  },
+  botMode: {
+    env: 'BOT_MODE',
+    description: 'Bot mode: transfer, amm, or crosschain',
+    defaultValue: 'transfer' as BotMode,
+    parseEnv(val: string) {
+      if (!(BotMode as readonly string[]).includes(val)) {
+        throw new Error(`Invalid value for BOT_MODE: ${val}`);
+      }
+      return val as BotMode;
+    },
+  },
+  l2ToL1MessagesPerTx: {
+    env: 'BOT_L2_TO_L1_MESSAGES_PER_TX',
+    description: 'Number of L2→L1 messages per tx (crosschain mode)',
+    ...numberConfigHelper(1),
+  },
+  l1ToL2SeedCount: {
+    env: 'BOT_L1_TO_L2_SEED_COUNT',
+    description: 'Max L1→L2 messages to keep in-flight (crosschain mode)',
+    ...numberConfigHelper(1),
+  },
+  ...pickConfigMappings(dataConfigMappings, ['dataStoreMapSizeKb', 'dataDirectory']),
+};
+
+export function getBotConfigFromEnv(): BotConfig {
+  return getConfigFromMappings<BotConfig>(botConfigMappings);
+}
+
+export function getBotDefaultConfig(): BotConfig {
+  return getDefaultConfig<BotConfig>(botConfigMappings);
+}
+
+export function getVersions(): Partial<ComponentsVersions> {
+  return {
+    l2ProtocolContractsHash: protocolContractsHash.toString(),
+    l2CircuitsVkTreeRoot: getVKTreeRoot().toString(),
+  };
+}

package/src/cross_chain_bot.ts

@@ -0,0 +1,208 @@
+/**
+ * CrossChainBot exercises L2->L1 and L1->L2 messaging.
+ *
+ *   createAndSendTx                          onTxMined
+ *   ──────────────────────────────────────   ──────────────────────────────
+ *
+ *   1. SEED (fire-and-forget)                3. VERIFY L2->L1
+ *      if store has fewer pending messages       Query getTxEffect, confirm
+ *      than seedCount and no seed is              the expected L2->L1 messages
+ *      in-flight:                                appeared in tx effects.
+ *        * kick off L1 inbox tx
+ *        * store msg on completion
+ *
+ *   2. BUILD & SEND BATCH
+ *      Always:
+ *        N x create_l2_to_l1_message
+ *            (random content, fixed
+ *             L1 recipient)
+ *      If a ready L1->L2 msg exists:
+ *        1 x consume_message_from_
+ *            arbitrary_sender_public
+ *        delete consumed msg from store
+ *      Send batch tx (no wait)
+ *
+ */
+import { AztecAddress } from '@aztec-labs/aztec.js/addresses';
+import { BatchCall, NO_WAIT } from '@aztec-labs/aztec.js/contracts';
+import { isL1ToL2MessageReady } from '@aztec-labs/aztec.js/messaging';
+import type { TxHash, TxReceipt } from '@aztec-labs/aztec.js/tx';
+import type { ExtendedViemWalletClient } from '@aztec-labs/ethereum/types';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
+import type { TestContract } from '@aztec-labs/noir-test-contracts.js/Test';
+import type { BlockTag } from '@aztec-labs/stdlib/block';
+import type { AztecNode, AztecNodeAdmin } from '@aztec-labs/stdlib/interfaces/client';
+import type { EmbeddedWallet } from '@aztec-labs/wallets/embedded';
+
+import { BaseBot } from './base_bot.js';
+import type { BotConfig } from './config.js';
+import { BotFactory } from './factory.js';
+import { seedL1ToL2Message } from './l1_to_l2_seeding.js';
+import type { BotStore, PendingL1ToL2Message } from './store/index.js';
+
+/** Stale message threshold: messages older than this are removed. */
+const STALE_MESSAGE_THRESHOLD_MS = 2 * 60 * 60 * 1000; // 2 hours
+
+/** Bot that exercises both L2→L1 and L1→L2 cross-chain messaging. */
+export class CrossChainBot extends BaseBot {
+  private l2ToL1Sent = 0;
+  private l1ToL2Consumed = 0;
+  private pendingSeedPromise: Promise<void> | undefined;
+
+  protected constructor(
+    node: AztecNode,
+    wallet: EmbeddedWallet,
+    defaultAccountAddress: AztecAddress,
+    private readonly contract: TestContract,
+    private readonly l1Client: ExtendedViemWalletClient,
+    private readonly l1Recipient: EthAddress,
+    private readonly inboxAddress: EthAddress,
+    private readonly rollupVersion: bigint,
+    private readonly store: BotStore,
+    config: BotConfig,
+    private readonly syncChainTip?: BlockTag,
+  ) {
+    super(node, wallet, defaultAccountAddress, config);
+  }
+
+  static async create(
+    config: BotConfig,
+    wallet: EmbeddedWallet,
+    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, syncChainTip);
+    const { defaultAccountAddress, contract, l1Client, rollupVersion } = await factory.setupCrossChain();
+    const l1Recipient = EthAddress.fromString(l1Client.account!.address);
+    const { l1ContractAddresses } = await aztecNode.getNodeInfo();
+    const inboxAddress = EthAddress.fromString(l1ContractAddresses.inboxAddress.toString());
+    return new CrossChainBot(
+      aztecNode,
+      wallet,
+      defaultAccountAddress,
+      contract,
+      l1Client,
+      l1Recipient,
+      inboxAddress,
+      rollupVersion,
+      store,
+      config,
+      syncChainTip,
+    );
+  }
+
+  protected async createAndSendTx(logCtx: object): Promise<TxHash> {
+    const pendingMessages = await this.store.getUnconsumedL1ToL2Messages();
+
+    // Send an L1→L2 message if we're below the threshold and not already seeding one
+    if (pendingMessages.length < this.config.l1ToL2SeedCount && !this.pendingSeedPromise) {
+      this.pendingSeedPromise = this.seedNewL1ToL2Message()
+        .catch(err => this.log.warn(`Failed to seed L1→L2 message: ${err}`, logCtx))
+        .finally(() => {
+          this.pendingSeedPromise = undefined;
+        });
+    }
+
+    // Build batch: always L2→L1, optionally consume L1→L2
+    const calls = [];
+
+    // L2→L1: create messages with random content
+    for (let i = 0; i < this.config.l2ToL1MessagesPerTx; i++) {
+      calls.push(
+        this.contract.methods.create_l2_to_l1_message_arbitrary_recipient_public(Fr.random(), this.l1Recipient),
+      );
+    }
+
+    // L1→L2: consume oldest ready message if available
+    const readyMsg = await this.getReadyL1ToL2Message(pendingMessages);
+    if (readyMsg) {
+      calls.push(
+        this.contract.methods.consume_message_from_arbitrary_sender_public(
+          Fr.fromHexString(readyMsg.content),
+          Fr.fromHexString(readyMsg.secret),
+          EthAddress.fromString(readyMsg.sender),
+          new Fr(BigInt(readyMsg.globalLeafIndex)),
+        ),
+      );
+      // Delete consumed message immediately so it works with FOLLOW_CHAIN=NONE
+      await this.store.deleteL1ToL2Message(readyMsg.msgHash);
+      this.l1ToL2Consumed++;
+    } else {
+      this.log.warn(`No ready L1→L2 message to consume`, {
+        ...logCtx,
+        pendingCount: pendingMessages.length,
+      });
+    }
+
+    const batch = new BatchCall(this.wallet, calls);
+    const opts = this.getSendMethodOpts();
+
+    this.log.verbose(`Sending cross-chain batch with ${calls.length} calls`, logCtx);
+    const { txHash } = await batch.send({ ...opts, wait: NO_WAIT });
+    return txHash;
+  }
+
+  protected override async onTxMined(receipt: TxReceipt, logCtx: object): Promise<void> {
+    // Verify L2→L1 messages appeared in this tx's effects
+    const minedReceipt = await this.node.getTxReceipt(receipt.txHash, { includeTxEffect: true });
+    const l2ToL1MsgsRaw = minedReceipt.txEffect?.l2ToL1Msgs;
+    if (l2ToL1MsgsRaw) {
+      const l2ToL1Msgs = l2ToL1MsgsRaw.filter(m => !m.isZero());
+      if (l2ToL1Msgs.length >= this.config.l2ToL1MessagesPerTx) {
+        this.l2ToL1Sent += l2ToL1Msgs.length;
+      } else {
+        this.log.error(`Expected ${this.config.l2ToL1MessagesPerTx} L2→L1 messages but found ${l2ToL1Msgs.length}`, {
+          ...logCtx,
+          blockNumber: receipt.blockNumber,
+          txHash: receipt.txHash.toString(),
+        });
+      }
+    }
+
+    const pendingCount = (await this.store.getUnconsumedL1ToL2Messages()).length;
+    this.log.info(`CrossChainBot txs mined`, {
+      ...logCtx,
+      l2ToL1Sent: this.l2ToL1Sent,
+      l1ToL2Consumed: this.l1ToL2Consumed,
+      l1ToL2Pending: pendingCount,
+    });
+  }
+
+  /** Finds the oldest pending message that is ready for consumption. */
+  private async getReadyL1ToL2Message(
+    pendingMessages: PendingL1ToL2Message[],
+  ): Promise<PendingL1ToL2Message | undefined> {
+    const now = Date.now();
+    for (const msg of pendingMessages) {
+      const ready = await isL1ToL2MessageReady(this.node, Fr.fromHexString(msg.msgHash), this.syncChainTip);
+      if (ready) {
+        return msg;
+      }
+
+      // Time-based stale detection: if the message is old and still not ready, remove it
+      if (now - msg.timestamp > STALE_MESSAGE_THRESHOLD_MS) {
+        await this.store.deleteL1ToL2Message(msg.msgHash);
+        this.log.warn(`Removed stale L1→L2 message ${msg.msgHash}`);
+      }
+    }
+    return undefined;
+  }
+
+  /** Seeds a new L1→L2 message on L1 and stores it. */
+  private async seedNewL1ToL2Message(): Promise<void> {
+    await seedL1ToL2Message(
+      this.l1Client,
+      this.inboxAddress,
+      this.contract.address,
+      this.rollupVersion,
+      this.store,
+      this.log,
+    );
+  }
+}