@aztec/ethereum 0.0.1-commit.b655e406 → 0.0.1-commit.b9865e97

package/src/contracts/governance_proposer.ts

@@ -1,3 +1,4 @@
+import { SlotNumber } from '@aztec/foundation/branded-types';
 import { memoize } from '@aztec/foundation/decorators';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { GovernanceProposerAbi } from '@aztec/l1-artifacts/GovernanceProposerAbi';
@@ -14,11 +15,19 @@ import {
 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';
+import { ReadOnlyGovernanceContract, extractProposalIdFromLogs } from './governance.js';
 
 export class GovernanceProposerContract implements IEmpireBase {
   private readonly proposer: GetContractReturnType<typeof GovernanceProposerAbi, ViemClient>;
 
+  /**
+   * Cache of bytecode-existence checks keyed by payload address. The check is stable for a
+   * contract's lifetime -- a contract either has code or it does not, and code cannot be removed
+   * after deployment (selfdestruct aside, which is not relevant here). Safe to memoize
+   * indefinitely for the lifetime of this instance.
+   */
+  private readonly emptyPayloadCache: Map<Hex, boolean> = new Map();
+
   constructor(
     public readonly client: ViemClient,
     address: Hex | EthAddress,
@@ -54,15 +63,25 @@ export class GovernanceProposerContract implements IEmpireBase {
     return this.proposer.read.getInstance();
   }
 
-  public computeRound(slot: bigint): Promise<bigint> {
-    return this.proposer.read.computeRound([slot]);
+  public computeRound(slot: SlotNumber): Promise<bigint> {
+    return this.proposer.read.computeRound([BigInt(slot)]);
   }
 
   public async getRoundInfo(
     rollupAddress: Hex,
     round: bigint,
-  ): Promise<{ lastSignalSlot: bigint; payloadWithMostSignals: Hex; executed: boolean }> {
-    return await this.proposer.read.getRoundData([rollupAddress, round]);
+  ): Promise<{ lastSignalSlot: SlotNumber; payloadWithMostSignals: Hex; quorumReached: boolean; executed: boolean }> {
+    const result = await this.proposer.read.getRoundData([rollupAddress, round]);
+    const [signalCount, quorum] = await Promise.all([
+      this.proposer.read.signalCount([rollupAddress, round, result.payloadWithMostSignals]),
+      this.getQuorumSize(),
+    ]);
+    return {
+      lastSignalSlot: SlotNumber.fromBigInt(result.lastSignalSlot),
+      payloadWithMostSignals: result.payloadWithMostSignals,
+      quorumReached: signalCount >= quorum,
+      executed: result.executed,
+    };
   }
 
   public getPayloadSignals(rollupAddress: Hex, round: bigint, payload: Hex): Promise<bigint> {
@@ -72,13 +91,14 @@ export class GovernanceProposerContract implements IEmpireBase {
   public createSignalRequest(payload: Hex): L1TxRequest {
     return {
       to: this.address.toString(),
+      abi: GovernanceProposerAbi,
       data: encodeSignal(payload),
     };
   }
 
   public async createSignalRequestWithSignature(
     payload: Hex,
-    slot: bigint,
+    slot: SlotNumber,
     chainId: number,
     signerAddress: Hex,
     signer: (msg: TypedDataDefinition) => Promise<Hex>,
@@ -93,10 +113,56 @@ export class GovernanceProposerContract implements IEmpireBase {
     );
     return {
       to: this.address.toString(),
+      abi: GovernanceProposerAbi,
       data: encodeSignalWithSignature(payload, signature),
     };
   }
 
+  /**
+   * Resolves the Governance contract this proposer submits winners to. Lazily reads
+   * `GovernanceProposer.getGovernance()` (which itself looks the address up via the registry) and
+   * memoizes the resulting wrapper.
+   */
+  @memoize
+  public async getGovernance(): Promise<ReadOnlyGovernanceContract> {
+    const address = await this.proposer.read.getGovernance();
+    return new ReadOnlyGovernanceContract(address, this.client);
+  }
+
+  /**
+   * Returns true iff the given original payload is currently the subject of a live (non-terminal)
+   * Governance proposal. Delegates to `ReadOnlyGovernanceContract.hasActiveProposalWithPayload`, which
+   * implements the actual sweep against the Governance contract -- this method exists only as a
+   * convenience wrapper so callers that already hold a GovernanceProposer reference don't have to
+   * resolve the Governance address themselves.
+   */
+  public async hasActiveProposalWithPayload(payload: Hex): Promise<boolean> {
+    const governance = await this.getGovernance();
+    return governance.hasActiveProposalWithPayload(payload);
+  }
+
+  /**
+   * Returns true if the given payload address has no deployed bytecode. Used as a cheap
+   * pre-flight check before casting a governance signal — voting for a zero-code address
+   * is unrecoverable.
+   *
+   * We only cache the `false` result (address has bytecode). The `true` result is NOT
+   * cached because a CREATE2-redeployed address could go from empty to populated, and
+   * caching `true` would make us keep skipping a payload that later becomes valid.
+   */
+  public async isPayloadEmpty(payload: EthAddress): Promise<boolean> {
+    const key = payload.toString() as Hex;
+    if (this.emptyPayloadCache.get(key) === false) {
+      return false;
+    }
+    const code = await this.client.getCode({ address: key });
+    const isEmpty = !code || code === '0x';
+    if (!isEmpty) {
+      this.emptyPayloadCache.set(key, false);
+    }
+    return isEmpty;
+  }
+
   public async submitRoundWinner(
     round: bigint,
     l1TxUtils: L1TxUtils,
@@ -106,8 +172,9 @@ export class GovernanceProposerContract implements IEmpireBase {
   }> {
     const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
       to: this.address.toString(),
+      abi: GovernanceProposerAbi,
       data: encodeFunctionData({
-        abi: this.proposer.abi,
+        abi: GovernanceProposerAbi,
         functionName: 'submitRoundWinner',
         args: [round],
       }),

package/src/contracts/inbox.ts

@@ -1,19 +1,34 @@
-import { Buffer16 } from '@aztec/foundation/buffer';
+import { maxBigint } from '@aztec/foundation/bigint';
+import { CheckpointNumber } from '@aztec/foundation/branded-types';
+import { Buffer16, Buffer32 } from '@aztec/foundation/buffer';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { InboxAbi } from '@aztec/l1-artifacts/InboxAbi';
 
 import { type BlockTag, type GetContractReturnType, type Hex, getContract } from 'viem';
 
 import { getPublicClient } from '../client.js';
-import type { DeployL1ContractsReturnType } from '../deploy_l1_contracts.js';
+import type { DeployAztecL1ContractsReturnType } from '../deploy_aztec_l1_contracts.js';
 import type { L1ReaderConfig } from '../l1_reader.js';
 import type { ViemClient } from '../types.js';
+import type { L1EventLog } from './log.js';
 import { checkBlockTag } from './utils.js';
 
+/** Arguments for the MessageSent event. */
+export type MessageSentArgs = {
+  index: bigint;
+  leaf: Fr;
+  checkpointNumber: CheckpointNumber;
+  rollingHash: Buffer16;
+};
+
+/** Log type for MessageSent events. */
+export type MessageSentLog = L1EventLog<MessageSentArgs>;
+
 export class InboxContract {
   private readonly inbox: GetContractReturnType<typeof InboxAbi, ViemClient>;
 
-  static getFromL1ContractsValues(deployL1ContractsValues: DeployL1ContractsReturnType) {
+  static getFromL1ContractsValues(deployL1ContractsValues: DeployAztecL1ContractsReturnType) {
     const {
       l1Client,
       l1ContractAddresses: { inboxAddress },
@@ -23,7 +38,7 @@ export class InboxContract {
 
   static getFromConfig(config: L1ReaderConfig) {
     const client = getPublicClient(config);
-    const address = config.l1Contracts.inboxAddress.toString();
+    const address = config.inboxAddress.toString();
     return new InboxContract(client, address);
   }
 
@@ -45,6 +60,11 @@ export class InboxContract {
     return this.inbox;
   }
 
+  public async getLag(opts: { blockTag?: BlockTag; blockNumber?: bigint } = {}): Promise<bigint> {
+    await checkBlockTag(opts.blockNumber, this.client);
+    return await this.inbox.read.LAG(opts);
+  }
+
   public async getState(opts: { blockTag?: BlockTag; blockNumber?: bigint } = {}): Promise<InboxContractState> {
     await checkBlockTag(opts.blockNumber, this.client);
     const state = await this.inbox.read.getState(opts);
@@ -54,6 +74,46 @@ export class InboxContract {
       treeInProgress: state.inProgress,
     };
   }
+
+  /** Fetches MessageSent events within the given block range. */
+  async getMessageSentEvents(fromBlock: bigint, toBlock: bigint): Promise<MessageSentLog[]> {
+    const logs = await this.inbox.getEvents.MessageSent({}, { fromBlock, toBlock });
+    return logs
+      .filter(log => log.blockNumber! >= fromBlock && log.blockNumber! <= toBlock)
+      .map(log => this.mapMessageSentLog(log));
+  }
+
+  /** Fetches MessageSent events for a specific message hash around a specific block. */
+  async getMessageSentEventByHash(msgHash: Hex, aroundL1BlockNumber: bigint): Promise<MessageSentLog> {
+    // We don't use blockHash here because we don't want the query to throw if the L1 block number no longer exists on chain
+    // due to an L1 reorg. The use case for this method is usually checking if a message still exists on the Inbox after
+    // a reorg, so it's possible the message was moved one block up or down, and that the original L1 block where we
+    // saw it no longer exists, rendering the block-by-hash approach invalid.
+    const [log] = await this.inbox.getEvents.MessageSent(
+      { hash: msgHash },
+      { fromBlock: maxBigint(aroundL1BlockNumber - 5n, 1n), toBlock: aroundL1BlockNumber + 5n },
+    );
+    return log && this.mapMessageSentLog(log);
+  }
+
+  private mapMessageSentLog(log: {
+    blockNumber: bigint | null;
+    blockHash: `0x${string}` | null;
+    transactionHash: `0x${string}` | null;
+    args: { index?: bigint; hash?: `0x${string}`; checkpointNumber?: bigint; rollingHash?: `0x${string}` };
+  }): MessageSentLog {
+    return {
+      l1BlockNumber: log.blockNumber!,
+      l1BlockHash: Buffer32.fromString(log.blockHash!),
+      l1TransactionHash: log.transactionHash!,
+      args: {
+        index: log.args.index!,
+        leaf: Fr.fromString(log.args.hash!),
+        checkpointNumber: CheckpointNumber.fromBigInt(log.args.checkpointNumber!),
+        rollingHash: Buffer16.fromString(log.args.rollingHash!),
+      },
+    };
+  }
 }
 
 export type InboxContractState = {

package/src/contracts/index.ts

@@ -1,14 +1,17 @@
+export * from './chain_state_override.js';
 export * from './empire_base.js';
 export * from './errors.js';
 export * from './fee_asset_handler.js';
+export * from './fee_asset_price_oracle.js';
 export * from './fee_juice.js';
 export * from './governance.js';
 export * from './governance_proposer.js';
 export * from './gse.js';
 export * from './inbox.js';
+export * from './log.js';
 export * from './multicall.js';
+export * from './outbox.js';
 export * from './registry.js';
 export * from './rollup.js';
-export * from './empire_slashing_proposer.js';
-export * from './tally_slashing_proposer.js';
+export * from './slashing_proposer.js';
 export * from './slasher_contract.js';

package/src/contracts/log.ts

@@ -0,0 +1,13 @@
+import type { Buffer32 } from '@aztec/foundation/buffer';
+
+/** Base L1 event log with common fields. */
+export type L1EventLog<T> = {
+  /** L1 block number where the event was emitted. */
+  l1BlockNumber: bigint;
+  /** L1 block hash. */
+  l1BlockHash: Buffer32;
+  /** L1 transaction hash that emitted the event. */
+  l1TransactionHash: `0x${string}`;
+  /** Event-specific arguments. */
+  args: T;
+};

package/src/contracts/multicall.ts

@@ -1,123 +1,264 @@
-import { toHex as toPaddedHex } from '@aztec/foundation/bigint-buffer';
-import { TimeoutError } from '@aztec/foundation/error';
+import { EthAddress } from '@aztec/foundation/eth-address';
 import type { Logger } from '@aztec/foundation/log';
 
-import { type EncodeFunctionDataParameters, type Hex, encodeFunctionData, multicall3Abi } from 'viem';
+import {
+  type Abi,
+  type Address,
+  type BlockOverrides,
+  type Hex,
+  type RequiredBy,
+  type StateOverride,
+  type TransactionReceipt,
+  decodeFunctionResult,
+  encodeFunctionData,
+  multicall3Abi,
+} from 'viem';
 
 import type { L1BlobInputs, L1TxConfig, L1TxRequest, L1TxUtils } from '../l1_tx_utils/index.js';
 import type { ExtendedViemWalletClient } from '../types.js';
-import { FormattedViemError, formatViemError } from '../utils.js';
-import { RollupContract } from './rollup.js';
+import { tryDecodeRevertReason } from '../utils.js';
 
 export const MULTI_CALL_3_ADDRESS = '0xcA11bde05977b3631167028862bE2a173976CA11' as const;
 
+/**
+ * Thrown by `Multicall3.forward` when the forwarder transaction lands but the receipt reports a
+ * reverted status. This is not expected (aggregate3 uses allowFailure: true), so callers should
+ * treat it as a fatal on-chain failure rather than retrying on a different publisher.
+ */
+export class MulticallForwarderRevertedError extends Error {
+  constructor(public readonly receipt: TransactionReceipt) {
+    super(`Multicall3 forwarder tx reverted: ${receipt.transactionHash}`);
+    this.name = 'MulticallForwarderRevertedError';
+  }
+}
+
+/** ABI fragment for aggregate3Value — not included in viem's multicall3Abi. */
+export const aggregate3ValueAbi = [
+  {
+    inputs: [
+      {
+        components: [
+          { internalType: 'address', name: 'target', type: 'address' },
+          { internalType: 'bool', name: 'allowFailure', type: 'bool' },
+          { internalType: 'uint256', name: 'value', type: 'uint256' },
+          { internalType: 'bytes', name: 'callData', type: 'bytes' },
+        ],
+        internalType: 'struct Multicall3.Call3Value[]',
+        name: 'calls',
+        type: 'tuple[]',
+      },
+    ],
+    name: 'aggregate3Value',
+    outputs: [
+      {
+        components: [
+          { internalType: 'bool', name: 'success', type: 'bool' },
+          { internalType: 'bytes', name: 'returnData', type: 'bytes' },
+        ],
+        internalType: 'struct Multicall3.Result[]',
+        name: 'returnData',
+        type: 'tuple[]',
+      },
+    ],
+    stateMutability: 'payable',
+    type: 'function',
+  },
+] as const;
+
+/** A single call to embed inside an aggregate3 simulation. The abi is used to decode revert reasons. */
+export type SimulateAggregate3Request = {
+  to: Address;
+  data: Hex;
+  /** Optional ABI used to decode the revert reason if this entry reverts. */
+  abi?: Abi;
+};
+
+export type SimulateAggregate3EntryResult = {
+  success: boolean;
+  /** Decoded revert reason text when `success === false` and a request abi was provided. */
+  revertReason?: string;
+  /** Raw return data hex. `'0x'` for successful entries with void return. */
+  returnData: Hex;
+};
+
+/**
+ * Outcome of a bundle simulation.
+ * - `decoded`: eth_simulateV1 ran and produced a per-entry Result[]. Use `entries` for filtering.
+ * - `fallback`: the node does not support eth_simulateV1; `fallbackGasEstimate` was returned and no
+ *    per-entry info is available. Caller should send the bundle as-is with a conservative gas cap.
+ */
+export type SimulateAggregate3Result =
+  | { kind: 'decoded'; entries: SimulateAggregate3EntryResult[]; gasUsed: bigint }
+  | { kind: 'fallback'; gasUsed: bigint };
+
+export type SimulateAggregate3Options = {
+  blockOverrides?: BlockOverrides<bigint, number>;
+  stateOverrides?: StateOverride;
+  /**
+   * If set, append a state override that fakes the sender's balance during the simulation so a
+   * low or zero balance does not cause the simulate to fail with insufficient funds. The fake
+   * balance is applied to `l1TxUtils.getSenderAddress()`.
+   */
+  fakeSenderBalance?: bigint;
+  /** Gas cap to pass on the simulate call itself (defaults to viem's behavior). */
+  gas?: bigint;
+  /** When eth_simulateV1 is unavailable, fall back to this gas estimate instead of throwing. */
+  fallbackGasEstimate?: bigint;
+};
+
 export class Multicall3 {
-  static async forward(
+  /**
+   * Returns true iff Multicall3 bytecode is deployed at MULTI_CALL_3_ADDRESS. An empty result from
+   * a non-existent contract would otherwise silently validate any bundle that uses Multicall3.
+   */
+  static async hasCode(l1TxUtils: L1TxUtils): Promise<boolean> {
+    const code = await l1TxUtils.getCode(EthAddress.fromString(MULTI_CALL_3_ADDRESS));
+    return !!code && code !== '0x';
+  }
+
+  /**
+   * Simulates an aggregate3 call composed of the given requests via eth_simulateV1 and decodes the
+   * per-entry Result[]. Entries that revert are returned with a decoded revertReason (if the request
+   * provided an abi).
+   *
+   * Use this to pre-validate a bundle before sending it through `Multicall3.forward`. The caller can
+   * drop reverted entries from the bundle and re-simulate with the reduced list to get an accurate
+   * `gasUsed`.
+   */
+  static async simulateAggregate3(
+    requests: SimulateAggregate3Request[],
+    l1TxUtils: L1TxUtils,
+    opts: SimulateAggregate3Options = {},
+  ): Promise<SimulateAggregate3Result> {
+    const calldata = encodeFunctionData({
+      abi: multicall3Abi,
+      functionName: 'aggregate3',
+      args: [
+        requests.map(r => ({
+          target: r.to,
+          callData: r.data,
+          allowFailure: true,
+        })),
+      ],
+    });
+
+    const stateOverrides: StateOverride = [...(opts.stateOverrides ?? [])];
+    if (opts.fakeSenderBalance !== undefined) {
+      stateOverrides.push({
+        address: l1TxUtils.getSenderAddress().toString(),
+        balance: opts.fakeSenderBalance,
+      });
+    }
+
+    const simResult = await l1TxUtils.simulate(
+      { to: MULTI_CALL_3_ADDRESS, data: calldata, gas: opts.gas },
+      opts.blockOverrides,
+      stateOverrides,
+      multicall3Abi,
+      { fallbackGasEstimate: opts.fallbackGasEstimate },
+    );
+
+    if (simResult.result === '0x') {
+      return { kind: 'fallback', gasUsed: simResult.gasUsed };
+    }
+
+    const decoded = decodeFunctionResult({
+      abi: multicall3Abi,
+      functionName: 'aggregate3',
+      data: simResult.result,
+    }) as readonly { success: boolean; returnData: `0x${string}` }[];
+
+    const entries: SimulateAggregate3EntryResult[] = decoded.map((entry, i) => {
+      if (entry.success) {
+        return { success: true, returnData: entry.returnData };
+      }
+      const abi = requests[i].abi;
+      const revertReason = abi ? tryDecodeRevertReason(entry.returnData, abi) : undefined;
+      return { success: false, returnData: entry.returnData, revertReason };
+    });
+
+    return { kind: 'decoded', entries, gasUsed: simResult.gasUsed };
+  }
+
+  /**
+   * Sends a batch of requests through aggregate3. Individual calls may fail (allowFailure: true),
+   * but the top-level multicall is expected to land successfully. Throws if the send fails or if
+   * the receipt reports a reverted status.
+   */
+  static async forward<TOptGasLimitRequired extends boolean>(
     requests: L1TxRequest[],
     l1TxUtils: L1TxUtils,
-    gasConfig: L1TxConfig | undefined,
+    gasConfig: TOptGasLimitRequired extends true ? RequiredBy<L1TxConfig, 'gasLimit'> : L1TxConfig | undefined,
     blobConfig: L1BlobInputs | undefined,
-    rollupAddress: Hex,
-    logger: Logger,
-    opts: { revertOnFailure?: boolean } = {},
+    opts: { gasLimitRequired?: TOptGasLimitRequired } = {},
   ) {
-    requests = requests.filter(request => request.to !== null);
-    const args = requests.map(r => ({
-      target: r.to!,
-      callData: r.data!,
-      allowFailure: !opts.revertOnFailure,
-    }));
-    const forwarderFunctionData: Required<EncodeFunctionDataParameters<typeof multicall3Abi, 'aggregate3'>> = {
+    if (opts.gasLimitRequired && !gasConfig?.gasLimit) {
+      throw new Error('Multicall gasLimit is required when gasLimitRequired is true');
+    }
+
+    const args = requests
+      .filter(request => request.to !== null)
+      .map(r => ({
+        target: r.to!,
+        callData: r.data!,
+        allowFailure: true,
+      }));
+    const encodedForwarderData = encodeFunctionData({
       abi: multicall3Abi,
       functionName: 'aggregate3',
       args: [args],
-    };
-
-    const encodedForwarderData = encodeFunctionData(forwarderFunctionData);
-
-    try {
-      const { receipt, state } = await l1TxUtils.sendAndMonitorTransaction(
-        { to: MULTI_CALL_3_ADDRESS, data: encodedForwarderData },
-        gasConfig,
-        blobConfig,
-      );
-
-      if (receipt.status === 'success') {
-        const stats = await l1TxUtils.getTransactionStats(receipt.transactionHash);
-        return { receipt, stats };
-      } else {
-        logger.error('Forwarder transaction failed', undefined, { receipt });
-
-        const args = {
-          ...forwarderFunctionData,
-          address: MULTI_CALL_3_ADDRESS,
-        };
-
-        let errorMsg: string | undefined;
-
-        if (blobConfig) {
-          const maxFeePerBlobGas = blobConfig.maxFeePerBlobGas ?? state.gasPrice.maxFeePerBlobGas;
-          if (maxFeePerBlobGas === undefined) {
-            errorMsg = 'maxFeePerBlobGas is required to get the error message';
-          } else {
-            logger.debug('Trying to get error from reverted tx with blob config');
-            errorMsg = await l1TxUtils.tryGetErrorFromRevertedTx(
-              encodedForwarderData,
-              args,
-              {
-                blobs: blobConfig.blobs,
-                kzg: blobConfig.kzg,
-                maxFeePerBlobGas,
-              },
-              [
-                {
-                  address: rollupAddress,
-                  stateDiff: [
-                    {
-                      slot: toPaddedHex(RollupContract.checkBlobStorageSlot, true),
-                      value: toPaddedHex(0n, true),
-                    },
-                  ],
-                },
-              ],
-            );
-          }
-        } else {
-          logger.debug('Trying to get error from reverted tx without blob config');
-          errorMsg = await l1TxUtils.tryGetErrorFromRevertedTx(encodedForwarderData, args, undefined, []);
-        }
-
-        return { receipt, errorMsg };
-      }
-    } catch (err) {
-      if (err instanceof TimeoutError) {
-        throw err;
-      }
+    });
 
-      for (const request of requests) {
-        logger.debug('Simulating request', { request });
-        const result = await l1TxUtils
-          .simulate(request, undefined, [
-            {
-              address: rollupAddress,
-              stateDiff: [
-                { slot: toPaddedHex(RollupContract.checkBlobStorageSlot, true), value: toPaddedHex(0n, true) },
-              ],
-            },
-          ])
-          .catch(err => formatViemError(err, request.abi));
-        if (result instanceof FormattedViemError) {
-          logger.error('Found error in simulation', result, {
-            to: request.to ?? 'null',
-            data: request.data,
-          });
-
-          return result;
-        }
-      }
-      logger.warn('Failed to get error from reverted tx', { err });
-      throw err;
+    const { receipt } = await l1TxUtils.sendAndMonitorTransaction(
+      {
+        to: MULTI_CALL_3_ADDRESS,
+        data: encodedForwarderData,
+        abi: multicall3Abi,
+      },
+      gasConfig,
+      blobConfig,
+    );
+
+    // This shouldn't happen. Any failure in individual calls is swallowed by forward since we set
+    // allowFailure to true for all calls, so a reverted status here would indicate a problem with
+    // the Multicall3 contract itself or the forwarder transaction (such as an out-of-gas).
+    if (receipt.status !== 'success') {
+      throw new MulticallForwarderRevertedError(receipt);
     }
+
+    const stats = await l1TxUtils.getTransactionStats(receipt.transactionHash);
+    return { receipt, stats, multicallData: encodedForwarderData };
+  }
+
+  /** Batch multiple value transfers into a single aggregate3Value call on Multicall3. */
+  static async forwardValue(calls: { to: Address; value: bigint }[], l1TxUtils: L1TxUtils, logger: Logger) {
+    const args = calls.map(c => ({
+      target: c.to,
+      allowFailure: false,
+      value: c.value,
+      callData: '0x' as Hex,
+    }));
+
+    const data = encodeFunctionData({
+      abi: aggregate3ValueAbi,
+      functionName: 'aggregate3Value',
+      args: [args],
+    });
+
+    const totalValue = calls.reduce((sum, c) => sum + c.value, 0n);
+
+    logger.info(`Sending aggregate3Value with ${calls.length} calls`, { totalValue });
+    const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
+      to: MULTI_CALL_3_ADDRESS,
+      data,
+      value: totalValue,
+    });
+
+    if (receipt.status !== 'success') {
+      throw new Error(`aggregate3Value transaction reverted: ${receipt.transactionHash}`);
+    }
+
+    return { receipt };
   }
 }