@aztec-labs/ethereum 6.0.0-rc.3 → 6.0.0

package/src/bn254/proof_of_possession_gas.ts

@@ -0,0 +1,54 @@
+import { computeBn254RegistrationDigestForPrivateKey } from './hash_to_point.js';
+
+/**
+ * Upper-bound model of the minimum gas stipend `Bn254LibWrapper.proofOfPossession` needs to accept a valid key, as a
+ * function of the `hashToPoint` loop work for that key:
+ * `fixed + perAttempt * attempts + perSqrtCall * sqrtCalls + ceil(memoryNumerator * attempts^2 / memoryDenominator)`.
+ */
+export type ProofOfPossessionGasModel = {
+  /** Work that does not depend on the key: pairing, scalar multiplications, hashing, stipend headroom. */
+  fixed: number;
+  /** Per loop attempt: keccak, ABI encoding and loop overhead. */
+  perAttempt: number;
+  /** Per attempt that reaches the modexp square root. */
+  perSqrtCall: number;
+  /** Memory growth from allocations that every attempt leaves behind, quadratic in the attempts. */
+  memoryNumerator: number;
+  memoryDenominator: number;
+};
+
+/**
+ * Conservative min-stipend fit of the BN254 proof-of-possession gas calibration vectors measured under amsterdam
+ * pricing, which matches osaka on this path. The vectors are aztec-packages `l1-contracts/test/fixtures/
+ * bn254_pop_gas_vectors.json`, copied verbatim to `fixtures/` next to this file.
+ */
+export const AMSTERDAM_PROOF_OF_POSSESSION_GAS_MODEL: ProofOfPossessionGasModel = {
+  fixed: 132_694,
+  perAttempt: 515,
+  perSqrtCall: 4_580,
+  memoryNumerator: 95_975,
+  memoryDenominator: 1_000_000,
+};
+
+/** Estimated minimum stipend for the proof-of-possession check of a key with the given `hashToPoint` work. */
+export function estimateProofOfPossessionGas(model: ProofOfPossessionGasModel, attempts: number, sqrtCalls: number) {
+  const memory = BigInt(model.memoryNumerator) * BigInt(attempts) ** 2n;
+  const denominator = BigInt(model.memoryDenominator);
+  return (
+    model.fixed +
+    model.perAttempt * attempts +
+    model.perSqrtCall * sqrtCalls +
+    Number((memory + denominator - 1n) / denominator)
+  );
+}
+
+/** Estimated minimum stipend for the proof-of-possession check of a BN254 BLS private key. */
+export function estimateBlsKeyProofOfPossessionGas(model: ProofOfPossessionGasModel, privateKey: string) {
+  const { attempts, sqrtCalls } = computeBn254RegistrationDigestForPrivateKey(privateKey);
+  return estimateProofOfPossessionGas(model, attempts, sqrtCalls);
+}
+
+/** Lowest gas estimate any key can have: one attempt that reaches the square root and succeeds. */
+export function minimumProofOfPossessionGas(model: ProofOfPossessionGasModel) {
+  return estimateProofOfPossessionGas(model, 1, 1);
+}

package/src/client.ts

@@ -19,7 +19,7 @@ import {
 import { mnemonicToAccount, privateKeyToAccount } from 'viem/accounts';
 import { foundry } from 'viem/chains';
 
-import { createEthereumChain } from './chain.js';
+import { createEthereumChain, isAnvilTestChain } from './chain.js';
 import type { ExtendedViemWalletClient, ViemPublicClient } from './types.js';
 
 type Config = {
@@ -45,7 +45,10 @@ export class L1RpcError extends Error {
 
 /** Creates a viem fallback HTTP transport for the given L1 RPC URLs. */
 export function makeL1HttpTransport(rpcUrls: string[], opts?: { timeout?: number }) {
-  return wrapL1RpcTransport(fallback(rpcUrls.map(url => http(url, { batch: false, timeout: opts?.timeout }))));
+  // viem caps response bodies at 10MB by default, which large getLogs or debug trace responses can exceed.
+  return wrapL1RpcTransport(
+    fallback(rpcUrls.map(url => http(url, { batch: false, timeout: opts?.timeout, maxResponseBodySize: false }))),
+  );
 }
 
 /** Returns the HTTP status from an L1 RPC error's cause chain, if one is available. */
@@ -158,7 +161,7 @@ export function createExtendedL1Client(
     account: hdAccount,
     chain,
     transport: makeL1HttpTransport(rpcUrls, { timeout: opts?.httpTimeoutMS }),
-    pollingInterval: pollingIntervalMS,
+    pollingInterval: pollingIntervalMS ?? (isAnvilTestChain(chain.id) ? 100 : undefined),
   }).extend(publicActions);
 
   return extendedClient;

package/src/contracts/errors.ts

@@ -5,9 +5,17 @@ export class BlockTagTooOldError extends Error {
   }
 }
 
-export class NoCommitteeError extends Error {
-  constructor() {
-    super('The committee does not exist on L1');
-    this.name = 'NoCommitteeError';
+/**
+ * The committee for an epoch cannot be served yet because its sample seed can still change on L1: the randao it
+ * samples has not been checkpointed, and the epoch that would checkpoint it is not over. Thrown by callers that cannot
+ * act without the committee and retry later.
+ */
+export class CommitteeNotStableError extends Error {
+  constructor(
+    public readonly epoch: bigint,
+    public readonly l1BlockNumber: bigint,
+  ) {
+    super(`The committee for epoch ${epoch} is not stable yet as of L1 block ${l1BlockNumber}`);
+    this.name = 'CommitteeNotStableError';
   }
 }

package/src/contracts/inbox.ts

@@ -192,6 +192,8 @@ export class InboxContract {
     blockNumber: bigint | null;
     blockHash: `0x${string}` | null;
     transactionHash: `0x${string}` | null;
+    transactionIndex: number | null;
+    logIndex: number | null;
     args: {
       hash?: `0x${string}`;
       inboxRollingHash?: `0x${string}`;
@@ -210,6 +212,8 @@ export class InboxContract {
       l1BlockNumber: log.blockNumber!,
       l1BlockHash: Buffer32.fromString(log.blockHash!),
       l1TransactionHash: log.transactionHash!,
+      l1TransactionIndex: log.transactionIndex!,
+      l1LogIndex: log.logIndex!,
       args: {
         index: message.index,
         leaf: Fr.fromString(log.args.hash!),

package/src/contracts/log.ts

@@ -8,10 +8,22 @@ export type L1EventLog<T> = {
   l1BlockHash: Buffer32;
   /** L1 transaction hash that emitted the event. */
   l1TransactionHash: `0x${string}`;
+  /** Index of the emitting transaction within its L1 block. */
+  l1TransactionIndex: number;
+  /** Index of the log within its L1 block (not within its transaction), as `eth_getLogs` reports it. */
+  l1LogIndex: number;
   /** Event-specific arguments. */
   args: T;
 };
 
+/** Orders L1 event logs by their position on L1: block number, then transaction index, then log index. */
+export function compareL1LogPosition(a: L1EventLog<unknown>, b: L1EventLog<unknown>): number {
+  if (a.l1BlockNumber !== b.l1BlockNumber) {
+    return a.l1BlockNumber < b.l1BlockNumber ? -1 : 1;
+  }
+  return a.l1TransactionIndex - b.l1TransactionIndex || a.l1LogIndex - b.l1LogIndex;
+}
+
 /**
  * Message fragments providers use to refuse a log query for being too wide or returning too much, the failures a
  * narrower range is known to fix. Matched on text because the JSON-RPC boundary leaves no error class or code behind

package/src/contracts/rollup.ts

@@ -12,6 +12,7 @@ import { Signature, type ViemSignature } from '@aztec-labs/foundation/eth-signat
 import { createLogger } from '@aztec-labs/foundation/log';
 import { makeBackoff, retry } from '@aztec-labs/foundation/retry';
 import { getErrorCause } from '@aztec-labs/foundation/types';
+import { Buffer } from 'buffer';
 import chunk from 'lodash.chunk';
 import {
   type AbiParameter,
@@ -342,6 +343,7 @@ export type CheckpointProposedArgs = {
 export type CheckpointProposedLog = L1EventLog<CheckpointProposedArgs>;
 
 const INSUFFICIENT_VALIDATOR_SET_SIZE_ERROR = 'ValidatorSelection__InsufficientValidatorSetSize';
+const EPOCH_NOT_STABLE_ERROR = 'ValidatorSelection__EpochNotStable';
 
 /** SlasherUpdated events are rare governance operations, so their watcher polls well below the client's interval. */
 const SLASHER_UPDATED_POLLING_INTERVAL_MS = 60_000;
@@ -354,6 +356,11 @@ function isValidatorSelectionError(err: unknown, errorName: string): boolean {
   );
 }
 
+/** Whether a rollup read reverted because the requested epoch's committee or seed can still change. */
+export function isEpochNotStableError(err: unknown): boolean {
+  return isValidatorSelectionError(err, EPOCH_NOT_STABLE_ERROR);
+}
+
 function decodeRpcRequestErrorName(err: unknown): string | undefined {
   const data = getErrorCause(err, RpcRequestError)?.data;
   if (!isHexString(data)) {
@@ -383,6 +390,7 @@ export class RollupContract {
   private readonly logger = createLogger('ethereum:rollup');
 
   private static cachedStfStorageSlot: Hex | undefined;
+  private static cachedValidatorSelectionStorageSlot: Hex | undefined;
   private cachedEscapeHatch?: {
     address: EthAddress;
     contract: GetContractReturnType<typeof EscapeHatchAbi, ViemClient>;
@@ -400,6 +408,13 @@ export class RollupContract {
     return (RollupContract.cachedStfStorageSlot ??= keccak256(Buffer.from('aztec.stf.storage', 'utf-8')));
   }
 
+  /** Base slot of the rollup's validator selection storage struct, whose first field maps epochs to committee commitments. */
+  static get validatorSelectionStorageSlot(): Hex {
+    return (RollupContract.cachedValidatorSelectionStorageSlot ??= keccak256(
+      Buffer.from('aztec.validator_selection.storage', 'utf-8'),
+    ));
+  }
+
   static getFromL1ContractsValues(deployL1ContractsValues: DeployAztecL1ContractsReturnType) {
     const {
       l1Client,
@@ -645,15 +660,18 @@ export class RollupContract {
    * This function is intentionally defensive: any failure to query the escape hatch
    * (RPC issues, transient errors, etc.) is treated as "closed" to avoid callers
    * needing to sprinkle try/catch everywhere.
+   *
+   * `options.blockNumber` pins only the hatch's `isHatchOpen` read: the escape hatch address is always resolved at the
+   * latest L1 block.
    */
-  async isEscapeHatchOpen(epoch: EpochNumber): Promise<boolean> {
+  async isEscapeHatchOpen(epoch: EpochNumber, options?: { blockNumber?: bigint }): Promise<boolean> {
     try {
       const escapeHatch = await this.getEscapeHatchContract();
       if (!escapeHatch) {
         return false;
       }
 
-      const [isOpen] = await escapeHatch.read.isHatchOpen([BigInt(epoch)]);
+      const [isOpen] = await escapeHatch.read.isHatchOpen([BigInt(epoch)], options);
       return isOpen;
     } catch (err) {
       this.logger.warn('isEscapeHatchOpen failed (treating as closed); RPC or contract error may cause liveness risk', {
@@ -745,13 +763,14 @@ export class RollupContract {
     return this.rollup.read.getEthPerFeeAsset();
   }
 
-  async getCommitteeAt(timestamp: bigint): Promise<EthAddress[] | undefined> {
+  async getCommitteeAt(timestamp: bigint, options?: { blockNumber?: bigint }): Promise<EthAddress[] | undefined> {
     const { result } = await this.client
       .simulateContract({
         address: this.address,
         abi: RollupAbi,
         functionName: 'getCommitteeAt',
         args: [timestamp],
+        blockNumber: options?.blockNumber,
       })
       .catch(e => {
         if (isValidatorSelectionError(e, INSUFFICIENT_VALIDATOR_SET_SIZE_ERROR)) {
@@ -763,8 +782,8 @@ export class RollupContract {
     return result ? result.map(addr => EthAddress.fromString(addr)) : undefined;
   }
 
-  async getSampleSeedAt(timestamp: bigint): Promise<Buffer32> {
-    return Buffer32.fromBigInt(await this.rollup.read.getSampleSeedAt([timestamp]));
+  async getSampleSeedAt(timestamp: bigint, options?: { blockNumber?: bigint }): Promise<Buffer32> {
+    return Buffer32.fromBigInt(await this.rollup.read.getSampleSeedAt([timestamp], options));
   }
 
   async getCurrentSampleSeed(): Promise<Buffer32> {
@@ -775,6 +794,26 @@ export class RollupContract {
     return EpochNumber.fromBigInt(await this.rollup.read.getCurrentEpoch());
   }
 
+  /**
+   * Whether `setupEpoch` has already run for the epoch, i.e. its committee commitment is stored, as of
+   * `options.blockNumber` (the latest L1 block by default).
+   * Read straight from storage because `getEpochCommitteeCommitment` computes the commitment when it is not stored.
+   */
+  async isEpochSetUp(epoch: EpochNumber, options?: { blockNumber?: bigint }): Promise<boolean> {
+    const slot = keccak256(
+      encodeAbiParameters(
+        [{ type: 'uint256' }, { type: 'uint256' }],
+        [BigInt(epoch), BigInt(RollupContract.validatorSelectionStorageSlot)],
+      ),
+    );
+    const value = await this.client.getStorageAt(
+      options?.blockNumber === undefined
+        ? { address: this.address, slot, blockTag: 'latest' }
+        : { address: this.address, slot, blockNumber: options.blockNumber },
+    );
+    return value !== undefined && hexToBigInt(value) !== 0n;
+  }
+
   async getCurrentEpochCommittee(): Promise<EthAddress[] | undefined> {
     const { result } = await this.client
       .simulateContract({
@@ -1317,6 +1356,21 @@ export class RollupContract {
     return this.rollup.read.getHasSubmitted([BigInt(epochNumber), BigInt(numberOfCheckpointsInEpoch), prover]);
   }
 
+  /**
+   * Calls getHasSubmittedFullEpoch directly. Returns whether the given prover's proof with the given length for the
+   * given epoch was registered as a full-epoch proof, which is the only kind that raises the prover's activity score.
+   */
+  public getHasSubmittedFullEpochProof(
+    epochNumber: EpochNumber,
+    numberOfCheckpointsInEpoch: number,
+    prover: Hex | EthAddress,
+  ): Promise<boolean> {
+    if (prover instanceof EthAddress) {
+      prover = prover.toString();
+    }
+    return this.rollup.read.getHasSubmittedFullEpoch([BigInt(epochNumber), BigInt(numberOfCheckpointsInEpoch), prover]);
+  }
+
   /**
    * Returns the minimum mana fee at the given timestamp.
    * @param options - Optional state override to simulate against, and optional L1 block number to pin the call
@@ -1391,7 +1445,8 @@ export class RollupContract {
     const block = await this.client.getBlock();
     const blockNumber = block.number ?? undefined;
     const ts = timestamp ?? block.timestamp;
-    const attesterSize = await this.getActiveAttesterCount({ blockNumber });
+    // Count at ts, matching the addresses below; the current count would truncate a shrunk set.
+    const attesterSize = await this.getAttesterCountAtTime(ts, { blockNumber });
     const gse = new GSEContract(this.client, await this.getGSE());
     const indices = Array.from({ length: attesterSize }, (_, i) => BigInt(i));
     const chunks = chunk(indices, 1000);
@@ -1822,6 +1877,8 @@ export class RollupContract {
         l1BlockNumber: log.blockNumber!,
         l1BlockHash: Buffer32.fromString(log.blockHash!),
         l1TransactionHash: log.transactionHash!,
+        l1TransactionIndex: log.transactionIndex!,
+        l1LogIndex: log.logIndex!,
         args: {
           checkpointNumber: CheckpointNumber.fromBigInt(log.args.checkpointNumber!),
           archive: Fr.fromString(log.args.archive!),