@aztec/epoch-cache 0.0.0-test.0

package/dest/config.d.ts

@@ -0,0 +1,4 @@
+import { type L1ContractsConfig, type L1ReaderConfig } from '@aztec/ethereum';
+export type EpochCacheConfig = Pick<L1ReaderConfig & L1ContractsConfig, 'l1RpcUrls' | 'l1ChainId' | 'viemPollingIntervalMS' | 'aztecSlotDuration' | 'ethereumSlotDuration' | 'aztecEpochDuration'>;
+export declare function getEpochCacheConfigEnvVars(): EpochCacheConfig;
+//# sourceMappingURL=config.d.ts.map

package/dest/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,cAAc,EAGpB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,gBAAgB,GAAG,IAAI,CACjC,cAAc,GAAG,iBAAiB,EAChC,WAAW,GACX,WAAW,GACX,uBAAuB,GACvB,mBAAmB,GACnB,sBAAsB,GACtB,oBAAoB,CACvB,CAAC;AAEF,wBAAgB,0BAA0B,IAAI,gBAAgB,CAE7D"}

package/dest/config.js

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

package/dest/epoch_cache.d.ts

@@ -0,0 +1,87 @@
+/// <reference types="node" resolution-mode="require"/>
+import { RollupContract } from '@aztec/ethereum';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { DateProvider } from '@aztec/foundation/timer';
+import { type L1RollupConstants } from '@aztec/stdlib/epoch-helpers';
+import { EventEmitter } from 'node:events';
+import { type EpochCacheConfig } from './config.js';
+type EpochAndSlot = {
+    epoch: bigint;
+    slot: bigint;
+    ts: bigint;
+};
+export interface EpochCacheInterface {
+    getCommittee(nextSlot: boolean): Promise<EthAddress[]>;
+    getEpochAndSlotNow(): EpochAndSlot;
+    getProposerIndexEncoding(epoch: bigint, slot: bigint, seed: bigint): `0x${string}`;
+    computeProposerIndex(slot: bigint, epoch: bigint, seed: bigint, size: bigint): bigint;
+    getProposerInCurrentOrNextSlot(): Promise<{
+        currentProposer: EthAddress;
+        nextProposer: EthAddress;
+        currentSlot: bigint;
+        nextSlot: bigint;
+    }>;
+    isInCommittee(validator: EthAddress): Promise<boolean>;
+}
+/**
+ * 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 declare class EpochCache extends EventEmitter<{
+    committeeChanged: [EthAddress[], bigint];
+}> implements EpochCacheInterface {
+    private rollup;
+    private readonly l1constants;
+    private readonly dateProvider;
+    private committee;
+    private cachedEpoch;
+    private cachedSampleSeed;
+    private readonly log;
+    constructor(rollup: RollupContract, initialValidators?: EthAddress[], initialSampleSeed?: bigint, l1constants?: L1RollupConstants, dateProvider?: DateProvider);
+    static create(rollupAddress: EthAddress, config?: EpochCacheConfig, deps?: {
+        dateProvider?: DateProvider;
+    }): Promise<EpochCache>;
+    private nowInSeconds;
+    getEpochAndSlotNow(): EpochAndSlot;
+    private getEpochAndSlotInNextSlot;
+    private getEpochAndSlotAtTimestamp;
+    /**
+     * Get the current validator set
+     *
+     * @param nextSlot - If true, get the validator set for the next slot.
+     * @returns The current validator set.
+     */
+    getCommittee(nextSlot?: boolean): Promise<EthAddress[]>;
+    /**
+     * Get the ABI encoding of the proposer index - see ValidatorSelectionLib.sol computeProposerIndex
+     */
+    getProposerIndexEncoding(epoch: bigint, slot: bigint, seed: bigint): `0x${string}`;
+    computeProposerIndex(slot: bigint, epoch: bigint, seed: bigint, size: bigint): bigint;
+    /**
+     * 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.
+     */
+    getProposerInCurrentOrNextSlot(): Promise<{
+        currentProposer: EthAddress;
+        nextProposer: EthAddress;
+        currentSlot: bigint;
+        nextSlot: bigint;
+    }>;
+    /**
+     * Check if a validator is in the current epoch's committee
+     */
+    isInCommittee(validator: EthAddress): Promise<boolean>;
+}
+export {};
+//# sourceMappingURL=epoch_cache.d.ts.map

package/dest/epoch_cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"epoch_cache.d.ts","sourceRoot":"","sources":["../src/epoch_cache.ts"],"names":[],"mappings":"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"}

package/dest/epoch_cache.js

@@ -0,0 +1,164 @@
+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 { EmptyL1RollupConstants, getEpochNumberAtTimestamp, getSlotAtTimestamp } from '@aztec/stdlib/epoch-helpers';
+import { EventEmitter } from 'node:events';
+import { createPublicClient, encodeAbiParameters, fallback, 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.l1RpcUrls, config.l1ChainId);
+        const publicClient = createPublicClient({
+            chain: chain.chainInfo,
+            transport: fallback(config.l1RpcUrls.map((url)=>http(url))),
+            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.d.ts

@@ -0,0 +1,3 @@
+export * from './epoch_cache.js';
+export * from './config.js';
+//# sourceMappingURL=index.d.ts.map

package/dest/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC"}

package/dest/index.js

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

package/dest/timestamp_provider.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=timestamp_provider.d.ts.map

package/dest/timestamp_provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp_provider.d.ts","sourceRoot":"","sources":["../src/timestamp_provider.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@aztec/epoch-cache",
+  "version": "0.0.0-test.0",
+  "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/ethereum": "0.0.0-test.0",
+    "@aztec/foundation": "0.0.0-test.0",
+    "@aztec/l1-artifacts": "0.0.0-test.0",
+    "@aztec/stdlib": "0.0.0-test.0",
+    "@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": 120000,
+    "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,
+  | 'l1RpcUrls'
+  | 'l1ChainId'
+  | 'viemPollingIntervalMS'
+  | 'aztecSlotDuration'
+  | 'ethereumSlotDuration'
+  | 'aztecEpochDuration'
+>;
+
+export function getEpochCacheConfigEnvVars(): EpochCacheConfig {
+  return { ...getL1ReaderConfigFromEnv(), ...getL1ContractsConfigEnvVars() };
+}

package/src/epoch_cache.ts

@@ -0,0 +1,231 @@
+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 {
+  EmptyL1RollupConstants,
+  type L1RollupConstants,
+  getEpochNumberAtTimestamp,
+  getSlotAtTimestamp,
+} from '@aztec/stdlib/epoch-helpers';
+
+import { EventEmitter } from 'node:events';
+import { createPublicClient, encodeAbiParameters, fallback, http, keccak256 } from 'viem';
+
+import { type EpochCacheConfig, getEpochCacheConfigEnvVars } from './config.js';
+
+type EpochAndSlot = {
+  epoch: bigint;
+  slot: bigint;
+  ts: bigint;
+};
+
+export interface EpochCacheInterface {
+  getCommittee(nextSlot: boolean): Promise<EthAddress[]>;
+  getEpochAndSlotNow(): EpochAndSlot;
+  getProposerIndexEncoding(epoch: bigint, slot: bigint, seed: bigint): `0x${string}`;
+  computeProposerIndex(slot: bigint, epoch: bigint, seed: bigint, size: bigint): bigint;
+  getProposerInCurrentOrNextSlot(): Promise<{
+    currentProposer: EthAddress;
+    nextProposer: EthAddress;
+    currentSlot: bigint;
+    nextSlot: bigint;
+  }>;
+  isInCommittee(validator: EthAddress): Promise<boolean>;
+}
+
+/**
+ * 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] }>
+  implements EpochCacheInterface
+{
+  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.l1RpcUrls, config.l1ChainId);
+    const publicClient = createPublicClient({
+      chain: chain.chainInfo,
+      transport: fallback(config.l1RpcUrls.map(url => http(url))),
+      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());
+  }
+
+  private getEpochAndSlotInNextSlot(): EpochAndSlot {
+    const nextSlotTs = this.nowInSeconds() + BigInt(this.l1constants.slotDuration);
+    return this.getEpochAndSlotAtTimestamp(nextSlotTs);
+  }
+
+  private 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';