@aztec/epoch-cache 0.75.0-commit.c03ba01a2a4122e43e90d5133ba017e54b90e9d2

package/dest/config.js

@@ -0,0 +1,7 @@
+import { getL1ContractsConfigEnvVars, getL1ReaderConfigFromEnv } from '@aztec/ethereum';
+export function getEpochCacheConfigEnvVars() {
+    return {
+        ...getL1ReaderConfigFromEnv(),
+        ...getL1ContractsConfigEnvVars()
+    };
+}

package/dest/epoch_cache.js

@@ -0,0 +1,164 @@
+import { EmptyL1RollupConstants, getEpochNumberAtTimestamp, getSlotAtTimestamp } from '@aztec/circuit-types';
+import { RollupContract, createEthereumChain } from '@aztec/ethereum';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { createLogger } from '@aztec/foundation/log';
+import { DateProvider } from '@aztec/foundation/timer';
+import { EventEmitter } from 'node:events';
+import { createPublicClient, encodeAbiParameters, http, keccak256 } from 'viem';
+import { getEpochCacheConfigEnvVars } from './config.js';
+/**
+ * Epoch cache
+ *
+ * This class is responsible for managing traffic to the l1 node, by caching the validator set.
+ * It also provides a method to get the current or next proposer, and to check who is in the current slot.
+ *
+ * If the epoch changes, then we update the stored validator set.
+ *
+ * Note: This class is very dependent on the system clock being in sync.
+ */ export class EpochCache extends EventEmitter {
+    rollup;
+    l1constants;
+    dateProvider;
+    committee;
+    cachedEpoch;
+    cachedSampleSeed;
+    log;
+    constructor(rollup, initialValidators = [], initialSampleSeed = 0n, l1constants = EmptyL1RollupConstants, dateProvider = new DateProvider()){
+        super(), this.rollup = rollup, this.l1constants = l1constants, this.dateProvider = dateProvider, this.log = createLogger('epoch-cache');
+        this.committee = initialValidators;
+        this.cachedSampleSeed = initialSampleSeed;
+        this.log.debug(`Initialized EpochCache with constants and validators`, {
+            l1constants,
+            initialValidators
+        });
+        this.cachedEpoch = getEpochNumberAtTimestamp(this.nowInSeconds(), this.l1constants);
+    }
+    static async create(rollupAddress, config, deps = {}) {
+        config = config ?? getEpochCacheConfigEnvVars();
+        const chain = createEthereumChain(config.l1RpcUrl, config.l1ChainId);
+        const publicClient = createPublicClient({
+            chain: chain.chainInfo,
+            transport: http(chain.rpcUrl),
+            pollingInterval: config.viemPollingIntervalMS
+        });
+        const rollup = new RollupContract(publicClient, rollupAddress.toString());
+        const [l1StartBlock, l1GenesisTime, initialValidators, sampleSeed] = await Promise.all([
+            rollup.getL1StartBlock(),
+            rollup.getL1GenesisTime(),
+            rollup.getCurrentEpochCommittee(),
+            rollup.getCurrentSampleSeed()
+        ]);
+        const l1RollupConstants = {
+            l1StartBlock,
+            l1GenesisTime,
+            slotDuration: config.aztecSlotDuration,
+            epochDuration: config.aztecEpochDuration,
+            ethereumSlotDuration: config.ethereumSlotDuration
+        };
+        return new EpochCache(rollup, initialValidators.map((v)=>EthAddress.fromString(v)), sampleSeed, l1RollupConstants, deps.dateProvider);
+    }
+    nowInSeconds() {
+        return BigInt(Math.floor(this.dateProvider.now() / 1000));
+    }
+    getEpochAndSlotNow() {
+        return this.getEpochAndSlotAtTimestamp(this.nowInSeconds());
+    }
+    getEpochAndSlotInNextSlot() {
+        const nextSlotTs = this.nowInSeconds() + BigInt(this.l1constants.slotDuration);
+        return this.getEpochAndSlotAtTimestamp(nextSlotTs);
+    }
+    getEpochAndSlotAtTimestamp(ts) {
+        return {
+            epoch: getEpochNumberAtTimestamp(ts, this.l1constants),
+            slot: getSlotAtTimestamp(ts, this.l1constants),
+            ts
+        };
+    }
+    /**
+   * Get the current validator set
+   *
+   * @param nextSlot - If true, get the validator set for the next slot.
+   * @returns The current validator set.
+   */ async getCommittee(nextSlot = false) {
+        // If the current epoch has changed, then we need to make a request to update the validator set
+        const { epoch: calculatedEpoch, ts } = nextSlot ? this.getEpochAndSlotInNextSlot() : this.getEpochAndSlotNow();
+        if (calculatedEpoch !== this.cachedEpoch) {
+            this.log.debug(`Updating validator set for new epoch ${calculatedEpoch}`, {
+                epoch: calculatedEpoch,
+                previousEpoch: this.cachedEpoch
+            });
+            const [committeeAtTs, sampleSeedAtTs] = await Promise.all([
+                this.rollup.getCommitteeAt(ts),
+                this.rollup.getSampleSeedAt(ts)
+            ]);
+            this.committee = committeeAtTs.map((v)=>EthAddress.fromString(v));
+            this.cachedEpoch = calculatedEpoch;
+            this.cachedSampleSeed = sampleSeedAtTs;
+            this.log.debug(`Updated validator set for epoch ${calculatedEpoch}`, {
+                commitee: this.committee
+            });
+            this.emit('committeeChanged', this.committee, calculatedEpoch);
+        }
+        return this.committee;
+    }
+    /**
+   * Get the ABI encoding of the proposer index - see ValidatorSelectionLib.sol computeProposerIndex
+   */ getProposerIndexEncoding(epoch, slot, seed) {
+        return encodeAbiParameters([
+            {
+                type: 'uint256',
+                name: 'epoch'
+            },
+            {
+                type: 'uint256',
+                name: 'slot'
+            },
+            {
+                type: 'uint256',
+                name: 'seed'
+            }
+        ], [
+            epoch,
+            slot,
+            seed
+        ]);
+    }
+    computeProposerIndex(slot, epoch, seed, size) {
+        return BigInt(keccak256(this.getProposerIndexEncoding(epoch, slot, seed))) % size;
+    }
+    /**
+   * Returns the current and next proposer
+   *
+   * We return the next proposer as the node will check if it is the proposer at the next ethereum block, which
+   * can be the next slot. If this is the case, then it will send proposals early.
+   *
+   * If we are at an epoch boundary, then we can update the cache for the next epoch, this is the last check
+   * we do in the validator client, so we can update the cache here.
+   */ async getProposerInCurrentOrNextSlot() {
+        // Validators are sorted by their index in the committee, and getValidatorSet will cache
+        const committee = await this.getCommittee();
+        const { slot: currentSlot, epoch: currentEpoch } = this.getEpochAndSlotNow();
+        const { slot: nextSlot, epoch: nextEpoch } = this.getEpochAndSlotInNextSlot();
+        // Compute the proposer in this and the next slot
+        const proposerIndex = this.computeProposerIndex(currentSlot, this.cachedEpoch, this.cachedSampleSeed, BigInt(committee.length));
+        // Check if the next proposer is in the next epoch
+        if (nextEpoch !== currentEpoch) {
+            await this.getCommittee(/*next slot*/ true);
+        }
+        const nextProposerIndex = this.computeProposerIndex(nextSlot, this.cachedEpoch, this.cachedSampleSeed, BigInt(committee.length));
+        const currentProposer = committee[Number(proposerIndex)];
+        const nextProposer = committee[Number(nextProposerIndex)];
+        return {
+            currentProposer,
+            nextProposer,
+            currentSlot,
+            nextSlot
+        };
+    }
+    /**
+   * Check if a validator is in the current epoch's committee
+   */ async isInCommittee(validator) {
+        const committee = await this.getCommittee();
+        return committee.some((v)=>v.equals(validator));
+    }
+}

package/dest/index.js

@@ -0,0 +1,2 @@
+export * from './epoch_cache.js';
+export * from './config.js';

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@aztec/epoch-cache",
+  "version": "0.75.0-commit.c03ba01a2a4122e43e90d5133ba017e54b90e9d2",
+  "type": "module",
+  "exports": {
+    ".": "./dest/index.js",
+    "./test": "./dest/test/index.js",
+    "./contracts": "./dest/contracts/index.js"
+  },
+  "typedocOptions": {
+    "entryPoints": [
+      "./src/index.ts"
+    ],
+    "name": "Epoch Cache",
+    "tsconfig": "./tsconfig.json"
+  },
+  "scripts": {
+    "build": "yarn clean && tsc -b",
+    "build:dev": "tsc -b --watch",
+    "clean": "rm -rf ./dest .tsbuildinfo",
+    "formatting": "run -T prettier --check ./src && run -T eslint ./src",
+    "formatting:fix": "run -T eslint --fix ./src && run -T prettier -w ./src",
+    "start:dev": "tsc-watch -p tsconfig.json --onSuccess 'yarn start'",
+    "start": "node ./dest/index.js",
+    "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}"
+  },
+  "inherits": [
+    "../package.common.json"
+  ],
+  "dependencies": {
+    "@aztec/circuit-types": "0.75.0-commit.c03ba01a2a4122e43e90d5133ba017e54b90e9d2",
+    "@aztec/ethereum": "0.75.0-commit.c03ba01a2a4122e43e90d5133ba017e54b90e9d2",
+    "@aztec/foundation": "0.75.0-commit.c03ba01a2a4122e43e90d5133ba017e54b90e9d2",
+    "@aztec/l1-artifacts": "0.75.0-commit.c03ba01a2a4122e43e90d5133ba017e54b90e9d2",
+    "@viem/anvil": "^0.0.10",
+    "dotenv": "^16.0.3",
+    "get-port": "^7.1.0",
+    "jest-mock-extended": "^3.0.7",
+    "tslib": "^2.4.0",
+    "viem": "2.22.8",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.5.0",
+    "@types/jest": "^29.5.0",
+    "@types/node": "^18.14.6",
+    "jest": "^29.5.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.0.4"
+  },
+  "files": [
+    "dest",
+    "src",
+    "!*.test.*"
+  ],
+  "types": "./dest/index.d.ts",
+  "jest": {
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.[cm]?js$": "$1"
+    },
+    "testRegex": "./src/.*\\.test\\.(js|mjs|ts)$",
+    "rootDir": "./src",
+    "transform": {
+      "^.+\\.tsx?$": [
+        "@swc/jest",
+        {
+          "jsc": {
+            "parser": {
+              "syntax": "typescript",
+              "decorators": true
+            },
+            "transform": {
+              "decoratorVersion": "2022-03"
+            }
+          }
+        }
+      ]
+    },
+    "extensionsToTreatAsEsm": [
+      ".ts"
+    ],
+    "reporters": [
+      "default"
+    ],
+    "testTimeout": 30000,
+    "setupFiles": [
+      "../../foundation/src/jest/setup.mjs"
+    ]
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/config.ts

@@ -0,0 +1,20 @@
+import {
+  type L1ContractsConfig,
+  type L1ReaderConfig,
+  getL1ContractsConfigEnvVars,
+  getL1ReaderConfigFromEnv,
+} from '@aztec/ethereum';
+
+export type EpochCacheConfig = Pick<
+  L1ReaderConfig & L1ContractsConfig,
+  | 'l1RpcUrl'
+  | 'l1ChainId'
+  | 'viemPollingIntervalMS'
+  | 'aztecSlotDuration'
+  | 'ethereumSlotDuration'
+  | 'aztecEpochDuration'
+>;
+
+export function getEpochCacheConfigEnvVars(): EpochCacheConfig {
+  return { ...getL1ReaderConfigFromEnv(), ...getL1ContractsConfigEnvVars() };
+}

package/src/epoch_cache.ts

@@ -0,0 +1,214 @@
+import {
+  EmptyL1RollupConstants,
+  type L1RollupConstants,
+  getEpochNumberAtTimestamp,
+  getSlotAtTimestamp,
+} from '@aztec/circuit-types';
+import { RollupContract, createEthereumChain } from '@aztec/ethereum';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { type Logger, createLogger } from '@aztec/foundation/log';
+import { DateProvider } from '@aztec/foundation/timer';
+
+import { EventEmitter } from 'node:events';
+import { createPublicClient, encodeAbiParameters, http, keccak256 } from 'viem';
+
+import { type EpochCacheConfig, getEpochCacheConfigEnvVars } from './config.js';
+
+type EpochAndSlot = {
+  epoch: bigint;
+  slot: bigint;
+  ts: bigint;
+};
+
+/**
+ * Epoch cache
+ *
+ * This class is responsible for managing traffic to the l1 node, by caching the validator set.
+ * It also provides a method to get the current or next proposer, and to check who is in the current slot.
+ *
+ * If the epoch changes, then we update the stored validator set.
+ *
+ * Note: This class is very dependent on the system clock being in sync.
+ */
+export class EpochCache extends EventEmitter<{ committeeChanged: [EthAddress[], bigint] }> {
+  private committee: EthAddress[];
+  private cachedEpoch: bigint;
+  private cachedSampleSeed: bigint;
+  private readonly log: Logger = createLogger('epoch-cache');
+
+  constructor(
+    private rollup: RollupContract,
+    initialValidators: EthAddress[] = [],
+    initialSampleSeed: bigint = 0n,
+    private readonly l1constants: L1RollupConstants = EmptyL1RollupConstants,
+    private readonly dateProvider: DateProvider = new DateProvider(),
+  ) {
+    super();
+    this.committee = initialValidators;
+    this.cachedSampleSeed = initialSampleSeed;
+
+    this.log.debug(`Initialized EpochCache with constants and validators`, { l1constants, initialValidators });
+
+    this.cachedEpoch = getEpochNumberAtTimestamp(this.nowInSeconds(), this.l1constants);
+  }
+
+  static async create(
+    rollupAddress: EthAddress,
+    config?: EpochCacheConfig,
+    deps: { dateProvider?: DateProvider } = {},
+  ) {
+    config = config ?? getEpochCacheConfigEnvVars();
+
+    const chain = createEthereumChain(config.l1RpcUrl, config.l1ChainId);
+    const publicClient = createPublicClient({
+      chain: chain.chainInfo,
+      transport: http(chain.rpcUrl),
+      pollingInterval: config.viemPollingIntervalMS,
+    });
+
+    const rollup = new RollupContract(publicClient, rollupAddress.toString());
+    const [l1StartBlock, l1GenesisTime, initialValidators, sampleSeed] = await Promise.all([
+      rollup.getL1StartBlock(),
+      rollup.getL1GenesisTime(),
+      rollup.getCurrentEpochCommittee(),
+      rollup.getCurrentSampleSeed(),
+    ] as const);
+
+    const l1RollupConstants: L1RollupConstants = {
+      l1StartBlock,
+      l1GenesisTime,
+      slotDuration: config.aztecSlotDuration,
+      epochDuration: config.aztecEpochDuration,
+      ethereumSlotDuration: config.ethereumSlotDuration,
+    };
+
+    return new EpochCache(
+      rollup,
+      initialValidators.map(v => EthAddress.fromString(v)),
+      sampleSeed,
+      l1RollupConstants,
+      deps.dateProvider,
+    );
+  }
+
+  private nowInSeconds(): bigint {
+    return BigInt(Math.floor(this.dateProvider.now() / 1000));
+  }
+
+  getEpochAndSlotNow(): EpochAndSlot {
+    return this.getEpochAndSlotAtTimestamp(this.nowInSeconds());
+  }
+
+  getEpochAndSlotInNextSlot(): EpochAndSlot {
+    const nextSlotTs = this.nowInSeconds() + BigInt(this.l1constants.slotDuration);
+    return this.getEpochAndSlotAtTimestamp(nextSlotTs);
+  }
+
+  getEpochAndSlotAtTimestamp(ts: bigint): EpochAndSlot {
+    return {
+      epoch: getEpochNumberAtTimestamp(ts, this.l1constants),
+      slot: getSlotAtTimestamp(ts, this.l1constants),
+      ts,
+    };
+  }
+
+  /**
+   * Get the current validator set
+   *
+   * @param nextSlot - If true, get the validator set for the next slot.
+   * @returns The current validator set.
+   */
+  async getCommittee(nextSlot: boolean = false): Promise<EthAddress[]> {
+    // If the current epoch has changed, then we need to make a request to update the validator set
+    const { epoch: calculatedEpoch, ts } = nextSlot ? this.getEpochAndSlotInNextSlot() : this.getEpochAndSlotNow();
+
+    if (calculatedEpoch !== this.cachedEpoch) {
+      this.log.debug(`Updating validator set for new epoch ${calculatedEpoch}`, {
+        epoch: calculatedEpoch,
+        previousEpoch: this.cachedEpoch,
+      });
+      const [committeeAtTs, sampleSeedAtTs] = await Promise.all([
+        this.rollup.getCommitteeAt(ts),
+        this.rollup.getSampleSeedAt(ts),
+      ]);
+      this.committee = committeeAtTs.map((v: `0x${string}`) => EthAddress.fromString(v));
+      this.cachedEpoch = calculatedEpoch;
+      this.cachedSampleSeed = sampleSeedAtTs;
+      this.log.debug(`Updated validator set for epoch ${calculatedEpoch}`, { commitee: this.committee });
+      this.emit('committeeChanged', this.committee, calculatedEpoch);
+    }
+
+    return this.committee;
+  }
+
+  /**
+   * Get the ABI encoding of the proposer index - see ValidatorSelectionLib.sol computeProposerIndex
+   */
+  getProposerIndexEncoding(epoch: bigint, slot: bigint, seed: bigint): `0x${string}` {
+    return encodeAbiParameters(
+      [
+        { type: 'uint256', name: 'epoch' },
+        { type: 'uint256', name: 'slot' },
+        { type: 'uint256', name: 'seed' },
+      ],
+      [epoch, slot, seed],
+    );
+  }
+
+  computeProposerIndex(slot: bigint, epoch: bigint, seed: bigint, size: bigint): bigint {
+    return BigInt(keccak256(this.getProposerIndexEncoding(epoch, slot, seed))) % size;
+  }
+
+  /**
+   * Returns the current and next proposer
+   *
+   * We return the next proposer as the node will check if it is the proposer at the next ethereum block, which
+   * can be the next slot. If this is the case, then it will send proposals early.
+   *
+   * If we are at an epoch boundary, then we can update the cache for the next epoch, this is the last check
+   * we do in the validator client, so we can update the cache here.
+   */
+  async getProposerInCurrentOrNextSlot(): Promise<{
+    currentProposer: EthAddress;
+    nextProposer: EthAddress;
+    currentSlot: bigint;
+    nextSlot: bigint;
+  }> {
+    // Validators are sorted by their index in the committee, and getValidatorSet will cache
+    const committee = await this.getCommittee();
+    const { slot: currentSlot, epoch: currentEpoch } = this.getEpochAndSlotNow();
+    const { slot: nextSlot, epoch: nextEpoch } = this.getEpochAndSlotInNextSlot();
+
+    // Compute the proposer in this and the next slot
+    const proposerIndex = this.computeProposerIndex(
+      currentSlot,
+      this.cachedEpoch,
+      this.cachedSampleSeed,
+      BigInt(committee.length),
+    );
+
+    // Check if the next proposer is in the next epoch
+    if (nextEpoch !== currentEpoch) {
+      await this.getCommittee(/*next slot*/ true);
+    }
+    const nextProposerIndex = this.computeProposerIndex(
+      nextSlot,
+      this.cachedEpoch,
+      this.cachedSampleSeed,
+      BigInt(committee.length),
+    );
+
+    const currentProposer = committee[Number(proposerIndex)];
+    const nextProposer = committee[Number(nextProposerIndex)];
+
+    return { currentProposer, nextProposer, currentSlot, nextSlot };
+  }
+
+  /**
+   * Check if a validator is in the current epoch's committee
+   */
+  async isInCommittee(validator: EthAddress): Promise<boolean> {
+    const committee = await this.getCommittee();
+    return committee.some(v => v.equals(validator));
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './epoch_cache.js';
+export * from './config.js';