@aztec/ethereum 3.0.0-nightly.20250930 → 3.0.0-nightly.20251002

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/ethereum",
-  "version": "3.0.0-nightly.20250930",
+  "version": "3.0.0-nightly.20251002",
   "type": "module",
   "exports": {
     ".": "./dest/index.js",
@@ -31,10 +31,10 @@
     "../package.common.json"
   ],
   "dependencies": {
-    "@aztec/blob-lib": "3.0.0-nightly.20250930",
-    "@aztec/constants": "3.0.0-nightly.20250930",
-    "@aztec/foundation": "3.0.0-nightly.20250930",
-    "@aztec/l1-artifacts": "3.0.0-nightly.20250930",
+    "@aztec/blob-lib": "3.0.0-nightly.20251002",
+    "@aztec/constants": "3.0.0-nightly.20251002",
+    "@aztec/foundation": "3.0.0-nightly.20251002",
+    "@aztec/l1-artifacts": "3.0.0-nightly.20251002",
     "@viem/anvil": "^0.0.10",
     "dotenv": "^16.0.3",
     "lodash.chunk": "^4.2.0",

package/src/config.ts

@@ -232,8 +232,8 @@ const TestnetEntryQueueConfig = {
 };
 
 const StagingIgnitionEntryQueueConfig = {
-  bootstrapValidatorSetSize: 24n,
-  bootstrapFlushSize: 24n,
+  bootstrapValidatorSetSize: 48n,
+  bootstrapFlushSize: 48n,
   normalFlushSizeMin: 1n,
   normalFlushSizeQuotient: 2048n,
   maxQueueFlushSize: 24n,

package/src/contracts/governance_proposer.ts

@@ -11,7 +11,7 @@ import {
   getContract,
 } from 'viem';
 
-import type { GasPrice, L1TxRequest, L1TxUtils } from '../l1_tx_utils/index.js';
+import type { L1TxRequest, L1TxUtils } from '../l1_tx_utils/index.js';
 import type { ViemClient } from '../types.js';
 import { type IEmpireBase, encodeSignal, encodeSignalWithSignature, signSignalWithSig } from './empire_base.js';
 import { extractProposalIdFromLogs } from './governance.js';
@@ -102,10 +102,9 @@ export class GovernanceProposerContract implements IEmpireBase {
     l1TxUtils: L1TxUtils,
   ): Promise<{
     receipt: TransactionReceipt;
-    gasPrice: GasPrice;
     proposalId: bigint;
   }> {
-    const { receipt, gasPrice } = await l1TxUtils.sendAndMonitorTransaction({
+    const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
       to: this.address.toString(),
       data: encodeFunctionData({
         abi: this.proposer.abi,
@@ -114,6 +113,6 @@ export class GovernanceProposerContract implements IEmpireBase {
       }),
     });
     const proposalId = extractProposalIdFromLogs(receipt.logs);
-    return { receipt, gasPrice, proposalId };
+    return { receipt, proposalId };
   }
 }

package/src/contracts/multicall.ts

@@ -36,7 +36,7 @@ export class Multicall3 {
     const encodedForwarderData = encodeFunctionData(forwarderFunctionData);
 
     try {
-      const { receipt, gasPrice } = await l1TxUtils.sendAndMonitorTransaction(
+      const { receipt, state } = await l1TxUtils.sendAndMonitorTransaction(
         {
           to: MULTI_CALL_3_ADDRESS,
           data: encodedForwarderData,
@@ -47,7 +47,7 @@ export class Multicall3 {
 
       if (receipt.status === 'success') {
         const stats = await l1TxUtils.getTransactionStats(receipt.transactionHash);
-        return { receipt, gasPrice, stats };
+        return { receipt, stats };
       } else {
         logger.error('Forwarder transaction failed', undefined, { receipt });
 
@@ -59,7 +59,7 @@ export class Multicall3 {
         let errorMsg: string | undefined;
 
         if (blobConfig) {
-          const maxFeePerBlobGas = blobConfig.maxFeePerBlobGas ?? gasPrice.maxFeePerBlobGas;
+          const maxFeePerBlobGas = blobConfig.maxFeePerBlobGas ?? state.gasPrice.maxFeePerBlobGas;
           if (maxFeePerBlobGas === undefined) {
             errorMsg = 'maxFeePerBlobGas is required to get the error message';
           } else {
@@ -90,7 +90,7 @@ export class Multicall3 {
           errorMsg = await l1TxUtils.tryGetErrorFromRevertedTx(encodedForwarderData, args, undefined, []);
         }
 
-        return { receipt, gasPrice, errorMsg };
+        return { receipt, errorMsg };
       }
     } catch (err) {
       if (err instanceof TimeoutError) {

package/src/deploy_l1_contracts.ts

@@ -45,6 +45,7 @@ import { RegistryContract } from './contracts/registry.js';
 import { RollupContract, SlashingProposerType } from './contracts/rollup.js';
 import {
   CoinIssuerArtifact,
+  DateGatedRelayerArtifact,
   FeeAssetArtifact,
   FeeAssetHandlerArtifact,
   GSEArtifact,
@@ -164,6 +165,8 @@ export interface DeployL1ContractsArgs extends Omit<L1ContractsConfig, keyof L1T
   realVerifier: boolean;
   /** The zk passport args */
   zkPassportArgs?: ZKPassportArgs;
+  /** If provided, use this token for BOTH fee and staking assets (skip deployments) */
+  existingTokenAddress?: EthAddress;
 }
 
 export interface ZKPassportArgs {
@@ -175,6 +178,80 @@ export interface ZKPassportArgs {
   zkPassportScope?: string;
 }
 
+// Minimal ERC20 ABI for validation purposes. We only read view methods.
+const ERC20_VALIDATION_ABI = [
+  {
+    type: 'function',
+    name: 'totalSupply',
+    stateMutability: 'view',
+    inputs: [],
+    outputs: [{ name: '', type: 'uint256' }],
+  },
+  {
+    type: 'function',
+    name: 'name',
+    stateMutability: 'view',
+    inputs: [],
+    outputs: [{ name: '', type: 'string' }],
+  },
+  {
+    type: 'function',
+    name: 'symbol',
+    stateMutability: 'view',
+    inputs: [],
+    outputs: [{ name: '', type: 'string' }],
+  },
+  {
+    type: 'function',
+    name: 'decimals',
+    stateMutability: 'view',
+    inputs: [],
+    outputs: [{ name: '', type: 'uint8' }],
+  },
+] as const;
+
+/**
+ * Validates that the provided address points to a contract that resembles an ERC20 token.
+ * Checks for contract code and attempts common ERC20 view calls.
+ * Throws an error if validation fails.
+ */
+export async function validateExistingErc20TokenAddress(
+  l1Client: ExtendedViemWalletClient,
+  tokenAddress: EthAddress,
+  logger: Logger,
+): Promise<void> {
+  const addressString = tokenAddress.toString();
+
+  // Ensure there is contract code at the address
+  const code = await l1Client.getCode({ address: addressString });
+  if (!code || code === '0x') {
+    throw new Error(`No contract code found at provided token address ${addressString}`);
+  }
+
+  const contract = getContract({
+    address: getAddress(addressString),
+    abi: ERC20_VALIDATION_ABI,
+    client: l1Client,
+  });
+
+  // Validate all required ERC20 methods in parallel
+  const checks = [
+    contract.read.totalSupply().then(total => typeof total === 'bigint'),
+    contract.read.name().then(() => true),
+    contract.read.symbol().then(() => true),
+    contract.read.decimals().then(dec => typeof dec === 'number' || typeof dec === 'bigint'),
+  ];
+
+  const results = await Promise.allSettled(checks);
+  const failedChecks = results.filter(result => result.status === 'rejected' || result.value !== true);
+
+  if (failedChecks.length > 0) {
+    throw new Error(`Address ${addressString} does not appear to implement ERC20 view methods`);
+  }
+
+  logger.verbose(`Validated existing token at ${addressString} appears to be ERC20-compatible`);
+}
+
 export const deploySharedContracts = async (
   l1Client: ExtendedViemWalletClient,
   deployer: L1Deployer,
@@ -187,19 +264,22 @@ export const deploySharedContracts = async (
 
   const txHashes: Hex[] = [];
 
-  const { address: feeAssetAddress } = await deployer.deploy(FeeAssetArtifact, [
-    'FeeJuice',
-    'FEE',
-    l1Client.account.address,
-  ]);
-  logger.verbose(`Deployed Fee Asset at ${feeAssetAddress}`);
+  let feeAssetAddress: EthAddress;
+  let stakingAssetAddress: EthAddress;
+  if (args.existingTokenAddress) {
+    await validateExistingErc20TokenAddress(l1Client, args.existingTokenAddress, logger);
+    feeAssetAddress = args.existingTokenAddress;
+    stakingAssetAddress = args.existingTokenAddress;
+    logger.verbose(`Using existing token for fee and staking assets at ${args.existingTokenAddress}`);
+  } else {
+    const deployedFee = await deployer.deploy(FeeAssetArtifact, ['FeeJuice', 'FEE', l1Client.account.address]);
+    feeAssetAddress = deployedFee.address;
+    logger.verbose(`Deployed Fee Asset at ${feeAssetAddress}`);
 
-  const { address: stakingAssetAddress } = await deployer.deploy(StakingAssetArtifact, [
-    'Staking',
-    'STK',
-    l1Client.account.address,
-  ]);
-  logger.verbose(`Deployed Staking Asset at ${stakingAssetAddress}`);
+    const deployedStaking = await deployer.deploy(StakingAssetArtifact, ['Staking', 'STK', l1Client.account.address]);
+    stakingAssetAddress = deployedStaking.address;
+    logger.verbose(`Deployed Staking Asset at ${stakingAssetAddress}`);
+  }
 
   const gseAddress = (
     await deployer.deploy(GSEArtifact, [
@@ -287,8 +367,8 @@ export const deploySharedContracts = async (
   let stakingAssetHandlerAddress: EthAddress | undefined = undefined;
   let zkPassportVerifierAddress: EthAddress | undefined = undefined;
 
-  // Only if not on mainnet will we deploy the handlers
-  if (l1Client.chain.id !== 1) {
+  // Only if not on mainnet will we deploy the handlers, and only when we control the token
+  if (l1Client.chain.id !== 1 && !args.existingTokenAddress) {
     /* -------------------------------------------------------------------------- */
     /*                          CHEAT CODES START HERE                            */
     /* -------------------------------------------------------------------------- */
@@ -379,19 +459,23 @@ export const deploySharedContracts = async (
 
   const rewardDistributorAddress = await registry.getRewardDistributor();
 
-  const blockReward = getRewardConfig(networkName).blockReward;
+  if (!args.existingTokenAddress) {
+    const blockReward = getRewardConfig(networkName).blockReward;
 
-  const funding = blockReward * 200000n;
-  const { txHash: fundRewardDistributorTxHash } = await deployer.sendTransaction({
-    to: feeAssetAddress.toString(),
-    data: encodeFunctionData({
-      abi: FeeAssetArtifact.contractAbi,
-      functionName: 'mint',
-      args: [rewardDistributorAddress.toString(), funding],
-    }),
-  });
+    const funding = blockReward * 200000n;
+    const { txHash: fundRewardDistributorTxHash } = await deployer.sendTransaction({
+      to: feeAssetAddress.toString(),
+      data: encodeFunctionData({
+        abi: FeeAssetArtifact.contractAbi,
+        functionName: 'mint',
+        args: [rewardDistributorAddress.toString(), funding],
+      }),
+    });
 
-  logger.verbose(`Funded reward distributor with ${funding} fee asset in ${fundRewardDistributorTxHash}`);
+    logger.verbose(`Funded reward distributor with ${funding} fee asset in ${fundRewardDistributorTxHash}`);
+  } else {
+    logger.verbose(`Skipping reward distributor funding as existing token is provided`);
+  }
 
   /* -------------------------------------------------------------------------- */
   /*                      FUND REWARD DISTRIBUTOR STOP                          */
@@ -610,21 +694,26 @@ export const deployRollup = async (
   logger.verbose(`All core contracts have been deployed`);
 
   if (args.feeJuicePortalInitialBalance && args.feeJuicePortalInitialBalance > 0n) {
-    const feeJuicePortalAddress = await rollupContract.getFeeJuicePortal();
+    // Skip funding when using an external token, as we likely don't have mint permissions
+    if (!('existingTokenAddress' in args) || !args.existingTokenAddress) {
+      const feeJuicePortalAddress = await rollupContract.getFeeJuicePortal();
 
-    // In fast mode, use the L1TxUtils to send transactions with nonce management
-    const { txHash: mintTxHash } = await deployer.sendTransaction({
-      to: addresses.feeJuiceAddress.toString(),
-      data: encodeFunctionData({
-        abi: FeeAssetArtifact.contractAbi,
-        functionName: 'mint',
-        args: [feeJuicePortalAddress.toString(), args.feeJuicePortalInitialBalance],
-      }),
-    });
-    logger.verbose(
-      `Funding fee juice portal with ${args.feeJuicePortalInitialBalance} fee juice in ${mintTxHash} (accelerated test deployments)`,
-    );
-    txHashes.push(mintTxHash);
+      // In fast mode, use the L1TxUtils to send transactions with nonce management
+      const { txHash: mintTxHash } = await deployer.sendTransaction({
+        to: addresses.feeJuiceAddress.toString(),
+        data: encodeFunctionData({
+          abi: FeeAssetArtifact.contractAbi,
+          functionName: 'mint',
+          args: [feeJuicePortalAddress.toString(), args.feeJuicePortalInitialBalance],
+        }),
+      });
+      logger.verbose(
+        `Funding fee juice portal with ${args.feeJuicePortalInitialBalance} fee juice in ${mintTxHash} (accelerated test deployments)`,
+      );
+      txHashes.push(mintTxHash);
+    } else {
+      logger.verbose('Skipping fee juice portal funding due to external token usage');
+    }
   }
 
   const slashFactoryAddress = (await deployer.deploy(SlashFactoryArtifact, [rollupAddress.toString()])).address;
@@ -747,6 +836,7 @@ export const handoverToGovernance = async (
   governanceAddress: EthAddress,
   logger: Logger,
   acceleratedTestDeployments: boolean | undefined,
+  useExternalToken: boolean = false,
 ) => {
   // We need to call a function on the registry to set the various contract addresses.
   const registryContract = getContract({
@@ -812,7 +902,10 @@ export const handoverToGovernance = async (
     txHashes.push(transferOwnershipTxHash);
   }
 
-  if (acceleratedTestDeployments || (await feeAsset.read.owner()) !== coinIssuerAddress.toString()) {
+  if (
+    !useExternalToken &&
+    (acceleratedTestDeployments || (await feeAsset.read.owner()) !== coinIssuerAddress.toString())
+  ) {
     const { txHash } = await deployer.sendTransaction(
       {
         to: feeAssetAddress.toString(),
@@ -839,23 +932,28 @@ export const handoverToGovernance = async (
     );
     logger.verbose(`Accept ownership of fee asset in ${acceptTokenOwnershipTxHash}`);
     txHashes.push(acceptTokenOwnershipTxHash);
+  } else if (useExternalToken) {
+    logger.verbose('Skipping fee asset ownership transfer due to external token usage');
   }
 
+  // Either deploy or at least predict the address of the date gated relayer
+  const dateGatedRelayer = await deployer.deploy(DateGatedRelayerArtifact, [
+    governanceAddress.toString(),
+    1798761600n, // 2027-01-01 00:00:00 UTC
+  ]);
+
   // If the owner is not the Governance contract, transfer ownership to the Governance contract
-  if (
-    acceleratedTestDeployments ||
-    (await coinIssuerContract.read.owner()) !== getAddress(governanceAddress.toString())
-  ) {
+  if (acceleratedTestDeployments || (await coinIssuerContract.read.owner()) === deployer.client.account.address) {
     const { txHash: transferOwnershipTxHash } = await deployer.sendTransaction({
       to: coinIssuerContract.address,
       data: encodeFunctionData({
         abi: CoinIssuerArtifact.contractAbi,
         functionName: 'transferOwnership',
-        args: [getAddress(governanceAddress.toString())],
+        args: [getAddress(dateGatedRelayer.address.toString())],
       }),
     });
     logger.verbose(
-      `Transferring the ownership of the coin issuer contract at ${coinIssuerAddress} to the Governance ${governanceAddress} in tx ${transferOwnershipTxHash}`,
+      `Transferring the ownership of the coin issuer contract at ${coinIssuerAddress} to the DateGatedRelayer ${dateGatedRelayer.address} in tx ${transferOwnershipTxHash}`,
     );
     txHashes.push(transferOwnershipTxHash);
   }
@@ -863,6 +961,8 @@ export const handoverToGovernance = async (
   // Wait for all actions to be mined
   await deployer.waitForDeployments();
   await Promise.all(txHashes.map(txHash => extendedClient.waitForTransactionReceipt({ hash: txHash })));
+
+  return { dateGatedRelayerAddress: dateGatedRelayer.address };
 };
 
 /*
@@ -1079,6 +1179,13 @@ export const deployL1Contracts = async (
   logger.info(`Deploying L1 contracts with config: ${jsonStringify(args)}`);
   validateConfig(args);
 
+  if (args.initialValidators && args.initialValidators.length > 0 && args.existingTokenAddress) {
+    throw new Error(
+      'Cannot deploy with both initialValidators and existingTokenAddress. ' +
+        'Initial validator funding requires minting tokens, which is not possible with an external token.',
+    );
+  }
+
   const l1Client = createExtendedL1Client(rpcUrls, account, chain);
 
   // Deploy multicall3 if it does not exist in this network
@@ -1148,7 +1255,7 @@ export const deployL1Contracts = async (
   await deployer.waitForDeployments();
 
   // Now that the rollup has been deployed and added to the registry, transfer ownership to governance
-  await handoverToGovernance(
+  const { dateGatedRelayerAddress } = await handoverToGovernance(
     l1Client,
     deployer,
     registryAddress,
@@ -1158,6 +1265,7 @@ export const deployL1Contracts = async (
     governanceAddress,
     logger,
     args.acceleratedTestDeployments,
+    !!args.existingTokenAddress,
   );
 
   logger.info(`Handing over to governance complete`);
@@ -1342,6 +1450,7 @@ export const deployL1Contracts = async (
       stakingAssetHandlerAddress,
       zkPassportVerifierAddress,
       coinIssuerAddress,
+      dateGatedRelayerAddress,
     },
   };
 };
@@ -1449,11 +1558,14 @@ export class L1Deployer {
     tx: L1TxRequest,
     options?: L1GasConfig,
   ): Promise<{ txHash: Hex; gasLimit: bigint; gasPrice: GasPrice }> {
-    return this.l1TxUtils.sendTransaction(tx, options);
+    return this.l1TxUtils.sendTransaction(tx, options).then(({ txHash, state }) => ({
+      txHash,
+      gasLimit: state.gasLimit,
+      gasPrice: state.gasPrice,
+    }));
   }
 }
 
-// docs:start:deployL1Contract
 /**
  * Helper function to deploy ETH contracts.
  * @param walletClient - A viem WalletClient.
@@ -1650,5 +1762,3 @@ export function getExpectedAddress(
     calldata,
   };
 }
-
-// docs:end:deployL1Contract

package/src/l1_artifacts.ts

@@ -1,6 +1,8 @@
 import {
   CoinIssuerAbi,
   CoinIssuerBytecode,
+  DateGatedRelayerAbi,
+  DateGatedRelayerBytecode,
   EmpireSlasherDeploymentExtLibAbi,
   EmpireSlasherDeploymentExtLibBytecode,
   EmpireSlashingProposerAbi,
@@ -149,6 +151,12 @@ export const CoinIssuerArtifact = {
   contractBytecode: CoinIssuerBytecode as Hex,
 };
 
+export const DateGatedRelayerArtifact = {
+  name: 'DateGatedRelayer',
+  contractAbi: DateGatedRelayerAbi,
+  contractBytecode: DateGatedRelayerBytecode as Hex,
+};
+
 export const GovernanceProposerArtifact = {
   name: 'GovernanceProposer',
   contractAbi: GovernanceProposerAbi,

package/src/l1_contract_addresses.ts

@@ -32,6 +32,7 @@ export type L1ContractAddresses = {
   stakingAssetHandlerAddress?: EthAddress | undefined;
   zkPassportVerifierAddress?: EthAddress | undefined;
   gseAddress?: EthAddress | undefined;
+  dateGatedRelayerAddress?: EthAddress | undefined;
 };
 
 export const L1ContractAddressesSchema = z.object({
@@ -51,12 +52,13 @@ export const L1ContractAddressesSchema = z.object({
   stakingAssetHandlerAddress: schemas.EthAddress.optional(),
   zkPassportVerifierAddress: schemas.EthAddress.optional(),
   gseAddress: schemas.EthAddress.optional(),
+  dateGatedRelayerAddress: schemas.EthAddress.optional(),
 }) satisfies ZodFor<L1ContractAddresses>;
 
 const parseEnv = (val: string) => EthAddress.fromString(val);
 
 export const l1ContractAddressesMapping: ConfigMappingsType<
-  Omit<L1ContractAddresses, 'gseAddress' | 'zkPassportVerifierAddress'>
+  Omit<L1ContractAddresses, 'gseAddress' | 'zkPassportVerifierAddress' | 'dateGatedRelayerAddress'>
 > = {
   registryAddress: {
     env: 'REGISTRY_CONTRACT_ADDRESS',

package/src/l1_tx_utils/factory.ts

@@ -13,7 +13,7 @@ import type { SigningCallback } from './types.js';
 
 export function createL1TxUtilsFromViemWallet(
   client: ExtendedViemWalletClient,
-  logger: Logger = createLogger('L1TxUtils'),
+  logger: Logger = createLogger('l1-tx-utils'),
   dateProvider: DateProvider = new DateProvider(),
   config?: Partial<L1TxUtilsConfig>,
   debugMaxGasLimit: boolean = false,
@@ -32,7 +32,7 @@ export function createL1TxUtilsFromViemWallet(
 export function createL1TxUtilsFromEthSigner(
   client: ViemClient,
   signer: EthSigner,
-  logger: Logger = createLogger('L1TxUtils'),
+  logger: Logger = createLogger('l1-tx-utils'),
   dateProvider: DateProvider = new DateProvider(),
   config?: Partial<L1TxUtilsConfig>,
   debugMaxGasLimit: boolean = false,