@aztec/stdlib 2.0.0-nightly.20250822 → 2.0.0-nightly.20250823

package/dest/slashing/types.js

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import { schemas } from '../schemas/index.js';
+export var OffenseType = /*#__PURE__*/ function(OffenseType) {
+    OffenseType[OffenseType["UNKNOWN"] = 0] = "UNKNOWN";
+    /** The data for proving an epoch was not publicly available, we slash its committee */ OffenseType[OffenseType["DATA_WITHHOLDING"] = 1] = "DATA_WITHHOLDING";
+    /** An epoch was not successfully proven in time, we slash its committee */ OffenseType[OffenseType["VALID_EPOCH_PRUNED"] = 2] = "VALID_EPOCH_PRUNED";
+    /** A proposer failed to attest or propose during an epoch according to the Sentinel */ OffenseType[OffenseType["INACTIVITY"] = 3] = "INACTIVITY";
+    /** A proposer sent an invalid block proposal over the p2p network to the committee */ OffenseType[OffenseType["BROADCASTED_INVALID_BLOCK_PROPOSAL"] = 4] = "BROADCASTED_INVALID_BLOCK_PROPOSAL";
+    /** A proposer pushed to L1 a block with insufficient committee attestations */ OffenseType[OffenseType["PROPOSED_INSUFFICIENT_ATTESTATIONS"] = 5] = "PROPOSED_INSUFFICIENT_ATTESTATIONS";
+    /** A proposer pushed to L1 a block with incorrect committee attestations (ie signature from a non-committee member) */ OffenseType[OffenseType["PROPOSED_INCORRECT_ATTESTATIONS"] = 6] = "PROPOSED_INCORRECT_ATTESTATIONS";
+    /** A committee member attested to a block that was built as a descendent of an invalid block (as in a block with invalid attestations) */ OffenseType[OffenseType["ATTESTED_DESCENDANT_OF_INVALID"] = 7] = "ATTESTED_DESCENDANT_OF_INVALID";
+    return OffenseType;
+}({});
+export const OffenseTypeSchema = z.nativeEnum(OffenseType);
+export const OffenseToBigInt = {
+    [0]: 0n,
+    [1]: 1n,
+    [2]: 2n,
+    [3]: 3n,
+    [4]: 4n,
+    [5]: 5n,
+    [6]: 6n,
+    [7]: 7n
+};
+export function bigIntToOffense(offense) {
+    switch(offense){
+        case 0n:
+            return 0;
+        case 1n:
+            return 1;
+        case 2n:
+            return 2;
+        case 3n:
+            return 3;
+        case 4n:
+            return 4;
+        case 5n:
+            return 5;
+        case 6n:
+            return 6;
+        case 7n:
+            return 7;
+        default:
+            throw new Error(`Unknown offense: ${offense}`);
+    }
+}
+export const OffenseSchema = z.object({
+    validator: schemas.EthAddress,
+    amount: schemas.BigInt,
+    offenseType: OffenseTypeSchema,
+    epochOrSlot: schemas.BigInt
+});
+export const SlashPayloadRoundSchema = z.object({
+    address: schemas.EthAddress,
+    timestamp: schemas.BigInt,
+    votes: schemas.BigInt,
+    round: schemas.BigInt,
+    slashes: z.array(z.object({
+        validator: schemas.EthAddress,
+        amount: schemas.BigInt,
+        offenses: z.array(z.object({
+            offenseType: OffenseTypeSchema,
+            epochOrSlot: schemas.BigInt
+        }))
+    }))
+});

package/dest/stats/stats.d.ts

@@ -164,9 +164,9 @@ export type L2BlockHandledStats = {
     /** Total duration in ms. */
     duration: number;
     /** Pending block number. */
-    unfinalisedBlockNumber: bigint;
+    unfinalizedBlockNumber: bigint;
     /** Proven block number. */
-    finalisedBlockNumber: bigint;
+    finalizedBlockNumber: bigint;
     /** Oldest historic block number. */
     oldestHistoricBlock: bigint;
 } & L2BlockStats;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/stdlib",
-  "version": "2.0.0-nightly.20250822",
+  "version": "2.0.0-nightly.20250823",
   "type": "module",
   "inherits": [
     "../package.common.json",
@@ -51,7 +51,8 @@
     "./snapshots": "./dest/snapshots/index.js",
     "./update-checker": "./dest/update-checker/index.js",
     "./zkpassport": "./dest/zkpassport/index.js",
-    "./slashing": "./dest/slashing/index.js"
+    "./slashing": "./dest/slashing/index.js",
+    "./l1-contracts": "./dest/l1-contracts/index.js"
   },
   "typedocOptions": {
     "entryPoints": [
@@ -68,12 +69,13 @@
     "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}"
   },
   "dependencies": {
-    "@aztec/bb.js": "2.0.0-nightly.20250822",
-    "@aztec/blob-lib": "2.0.0-nightly.20250822",
-    "@aztec/constants": "2.0.0-nightly.20250822",
-    "@aztec/ethereum": "2.0.0-nightly.20250822",
-    "@aztec/foundation": "2.0.0-nightly.20250822",
-    "@aztec/noir-noirc_abi": "2.0.0-nightly.20250822",
+    "@aztec/bb.js": "2.0.0-nightly.20250823",
+    "@aztec/blob-lib": "2.0.0-nightly.20250823",
+    "@aztec/constants": "2.0.0-nightly.20250823",
+    "@aztec/ethereum": "2.0.0-nightly.20250823",
+    "@aztec/foundation": "2.0.0-nightly.20250823",
+    "@aztec/l1-artifacts": "2.0.0-nightly.20250823",
+    "@aztec/noir-noirc_abi": "2.0.0-nightly.20250823",
     "@google-cloud/storage": "^7.15.0",
     "axios": "^1.9.0",
     "json-stringify-deterministic": "1.0.12",

package/src/block/l2_block.ts

@@ -110,6 +110,14 @@ export class L2Block {
     return this.header.getBlockNumber();
   }
 
+  get slot(): bigint {
+    return this.header.getSlot();
+  }
+
+  get timestamp(): bigint {
+    return this.header.globalVariables.timestamp;
+  }
+
   /**
    * Returns the block's hash (hash of block header).
    * @returns The block's hash.

package/src/interfaces/aztec-node-admin.ts

@@ -3,7 +3,7 @@ import { createSafeJsonRpcClient, defaultFetch } from '@aztec/foundation/json-rp
 import { z } from 'zod';
 
 import type { ApiSchemaFor } from '../schemas/schemas.js';
-import { type MonitoredSlashPayload, MonitoredSlashPayloadSchema } from '../slashing/index.js';
+import { type Offense, OffenseSchema, type SlashPayloadRound, SlashPayloadRoundSchema } from '../slashing/index.js';
 import { type ComponentsVersions, getVersioningResponseHandler } from '../versioning/index.js';
 import { type SequencerConfig, SequencerConfigSchema } from './configs.js';
 import { type ProverConfig, ProverConfigSchema } from './prover-client.js';
@@ -43,8 +43,11 @@ export interface AztecNodeAdmin {
   /** Resumes archiver and world state syncing. */
   resumeSync(): Promise<void>;
 
-  /** Returns all monitored payloads by the slasher. */
-  getSlasherMonitoredPayloads(): Promise<MonitoredSlashPayload[]>;
+  /** Returns all monitored payloads by the slasher for the current round. */
+  getSlashPayloads(): Promise<SlashPayloadRound[]>;
+
+  /** Returns all offenses applicable for the given round. */
+  getSlashOffenses(round: bigint | 'all' | 'current'): Promise<Offense[]>;
 }
 
 export type AztecNodeAdminConfig = SequencerConfig & ProverConfig & SlasherConfig & { maxTxPoolSize: number };
@@ -60,7 +63,11 @@ export const AztecNodeAdminApiSchema: ApiSchemaFor<AztecNodeAdmin> = {
   rollbackTo: z.function().args(z.number()).returns(z.void()),
   pauseSync: z.function().returns(z.void()),
   resumeSync: z.function().returns(z.void()),
-  getSlasherMonitoredPayloads: z.function().returns(z.array(MonitoredSlashPayloadSchema)),
+  getSlashPayloads: z.function().returns(z.array(SlashPayloadRoundSchema)),
+  getSlashOffenses: z
+    .function()
+    .args(z.union([z.bigint(), z.literal('all'), z.literal('current')]))
+    .returns(z.array(OffenseSchema)),
 };
 
 export function createAztecNodeAdminClient(

package/src/interfaces/epoch-prover.ts

@@ -33,7 +33,7 @@ export interface EpochProver extends Omit<IBlockFactory, 'setBlockCompleted'> {
   setBlockCompleted(blockNumber: number, expectedBlockHeader?: BlockHeader): Promise<L2Block>;
 
   /** Pads the epoch with empty block roots if needed and blocks until proven. Throws if proving has failed. */
-  finaliseEpoch(): Promise<{ publicInputs: RootRollupPublicInputs; proof: Proof; batchedBlobInputs: BatchedBlob }>;
+  finalizeEpoch(): Promise<{ publicInputs: RootRollupPublicInputs; proof: Proof; batchedBlobInputs: BatchedBlob }>;
 
   /** Cancels all proving jobs. */
   cancel(): void;

package/src/interfaces/slasher.ts

@@ -1,18 +1,19 @@
-import type { SecretValue } from '@aztec/foundation/config';
 import type { EthAddress } from '@aztec/foundation/eth-address';
 import { type ZodFor, schemas } from '@aztec/foundation/schemas';
 
 import { z } from 'zod';
 
+export type SlasherClientType = 'empire' | 'tally';
+
 export interface SlasherConfig {
   slashOverridePayload?: EthAddress;
   slashPayloadTtlSeconds: number; // TTL for payloads, in seconds
   slashPruneEnabled: boolean;
   slashPrunePenalty: bigint;
   slashPruneMaxPenalty: bigint;
-  slashInvalidBlockEnabled: boolean;
-  slashInvalidBlockPenalty: bigint;
-  slashInvalidBlockMaxPenalty: bigint;
+  slashBroadcastedInvalidBlockEnabled: boolean;
+  slashBroadcastedInvalidBlockPenalty: bigint;
+  slashBroadcastedInvalidBlockMaxPenalty: bigint;
   slashInactivityEnabled: boolean;
   slashInactivityCreateTargetPercentage: number; // 0-1, 0.9 means 90%. Must be greater than 0
   slashInactivitySignalTargetPercentage: number; // 0-1, 0.6 means 60%. Must be greater than 0
@@ -23,7 +24,11 @@ export interface SlasherConfig {
   slashProposeInvalidAttestationsMaxPenalty: bigint;
   slashAttestDescendantOfInvalidPenalty: bigint;
   slashAttestDescendantOfInvalidMaxPenalty: bigint;
-  slasherPrivateKey: SecretValue<string | undefined>; // Private key of the slasher account used for creating slash payloads
+  slashUnknownPenalty: bigint;
+  slashUnknownMaxPenalty: bigint;
+  slashOffenseExpirationRounds: number; // Number of rounds after which pending offenses expire
+  slashMaxPayloadSize: number; // Maximum number of offenses to include in a single slash payload
+  slashGracePeriodL2Slots: number; // Number of L2 slots to wait after genesis before slashing for most offenses
 }
 
 export const SlasherConfigSchema = z.object({
@@ -32,9 +37,9 @@ export const SlasherConfigSchema = z.object({
   slashPruneEnabled: z.boolean(),
   slashPrunePenalty: schemas.BigInt,
   slashPruneMaxPenalty: schemas.BigInt,
-  slashInvalidBlockEnabled: z.boolean(),
-  slashInvalidBlockPenalty: schemas.BigInt,
-  slashInvalidBlockMaxPenalty: schemas.BigInt,
+  slashBroadcastedInvalidBlockEnabled: z.boolean(),
+  slashBroadcastedInvalidBlockPenalty: schemas.BigInt,
+  slashBroadcastedInvalidBlockMaxPenalty: schemas.BigInt,
   slashInactivityEnabled: z.boolean(),
   slashInactivityCreateTargetPercentage: z.number(),
   slashInactivitySignalTargetPercentage: z.number(),
@@ -45,5 +50,9 @@ export const SlasherConfigSchema = z.object({
   slashProposeInvalidAttestationsMaxPenalty: schemas.BigInt,
   slashAttestDescendantOfInvalidPenalty: schemas.BigInt,
   slashAttestDescendantOfInvalidMaxPenalty: schemas.BigInt,
-  slasherPrivateKey: schemas.SecretValue(z.string().optional()),
+  slashUnknownPenalty: schemas.BigInt,
+  slashUnknownMaxPenalty: schemas.BigInt,
+  slashOffenseExpirationRounds: z.number(),
+  slashMaxPayloadSize: z.number(),
+  slashGracePeriodL2Slots: z.number(),
 }) satisfies ZodFor<SlasherConfig>;

package/src/interfaces/world_state.ts

@@ -20,7 +20,7 @@ export enum WorldStateRunningState {
 export interface WorldStateSyncStatus {
   latestBlockNumber: number;
   latestBlockHash: string;
-  finalisedBlockNumber: number;
+  finalizedBlockNumber: number;
   oldestHistoricBlockNumber: number;
   treesAreSynched: boolean;
 }
@@ -84,7 +84,7 @@ export interface WorldStateSynchronizer extends ForkMerkleTreeOperations {
 }
 
 export const WorldStateSyncStatusSchema = z.object({
-  finalisedBlockNumber: z.number().int().nonnegative(),
+  finalizedBlockNumber: z.number().int().nonnegative(),
   latestBlockNumber: z.number().int().nonnegative(),
   latestBlockHash: z.string(),
   oldestHistoricBlockNumber: z.number().int().nonnegative(),

package/src/l1-contracts/index.ts

@@ -0,0 +1 @@
+export * from './slash_factory.js';

package/src/l1-contracts/slash_factory.ts

@@ -0,0 +1,177 @@
+import { type L1TxRequest, type ViemClient, tryExtractEvent } from '@aztec/ethereum';
+import { maxBigint } from '@aztec/foundation/bigint';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { createLogger } from '@aztec/foundation/log';
+import { SlashFactoryAbi } from '@aztec/l1-artifacts/SlashFactoryAbi';
+
+import { type GetContractReturnType, type Hex, type Log, encodeFunctionData, getContract } from 'viem';
+
+import type { L1RollupConstants } from '../epoch-helpers/index.js';
+import {
+  OffenseToBigInt,
+  type SlashPayload,
+  type ValidatorSlash,
+  type ValidatorSlashOffense,
+  bigIntToOffense,
+} from '../slashing/index.js';
+
+export class SlashFactoryContract {
+  private readonly logger = createLogger('contracts:slash_factory');
+  private readonly contract: GetContractReturnType<typeof SlashFactoryAbi, ViemClient>;
+
+  constructor(
+    public readonly client: ViemClient,
+    address: Hex | EthAddress,
+  ) {
+    this.contract = getContract({
+      address: typeof address === 'string' ? address : address.toString(),
+      abi: SlashFactoryAbi,
+      client,
+    });
+  }
+
+  public get address() {
+    return EthAddress.fromString(this.contract.address);
+  }
+
+  public buildCreatePayloadRequest(slashes: ValidatorSlash[]): L1TxRequest {
+    const sorted = this.sortSlashes(slashes);
+
+    return {
+      to: this.contract.address,
+      data: encodeFunctionData({
+        abi: SlashFactoryAbi,
+        functionName: 'createSlashPayload',
+        args: [
+          sorted.map(d => d.validator.toString()),
+          sorted.map(d => d.amount),
+          sorted.map(d => d.offenses.map(packValidatorSlashOffense)),
+        ],
+      }),
+    };
+  }
+
+  /** Tries to extract a SlashPayloadCreated event from the given logs. */
+  public tryExtractSlashPayloadCreatedEvent(logs: Log[]) {
+    return tryExtractEvent(logs, this.address.toString(), SlashFactoryAbi, 'SlashPayloadCreated');
+  }
+
+  public async getSlashPayloadCreatedEvents(): Promise<SlashPayload[]> {
+    const events = await this.contract.getEvents.SlashPayloadCreated();
+    return Promise.all(
+      events.map(async event => {
+        const { validators, amounts, offenses } = event.args;
+        const slashes: ValidatorSlash[] = validators!.map((validator, i) => ({
+          validator: EthAddress.fromString(validator),
+          amount: amounts![i],
+          offenses: offenses![i].map(unpackValidatorSlashOffense),
+        }));
+
+        const block = await this.client.getBlock({ blockNumber: event.blockNumber, includeTransactions: false });
+        return { address: EthAddress.fromString(event.args.payloadAddress!), slashes, timestamp: block.timestamp };
+      }),
+    );
+  }
+
+  /**
+   * Searches for a slash payload in the events emitted by the contract.
+   * This method cannot query for historical payload events, it queries for payloads that have not yet expired.
+   * @param payloadAddress The address of the payload to search for.
+   * @param constants The L1 rollup constants needed for time calculations.
+   */
+  public async getSlashPayloadFromEvents(
+    payloadAddress: EthAddress,
+    settings: {
+      logsBatchSize?: number;
+      slashingRoundSize: number;
+      slashingPayloadLifetimeInRounds: number;
+    } & Pick<L1RollupConstants, 'slotDuration' | 'ethereumSlotDuration'>,
+  ): Promise<Omit<SlashPayload, 'votes'> | undefined> {
+    // We query for the log where the payload was emitted walking backwards until we go past payload expiration time
+    // Note that all log queries require a block range, and RPC providers cap the max range (eg quicknode is 10k blocks).
+    const { slashingRoundSize, slashingPayloadLifetimeInRounds, slotDuration, ethereumSlotDuration } = settings;
+    const currentBlockNumber = await this.client.getBlockNumber({ cacheTime: 0 });
+
+    // Why the +1 below? Just for good measure. Better err on the safe side.
+    const earliestBlockNumber = maxBigint(
+      0n,
+      currentBlockNumber -
+        ((BigInt(slashingPayloadLifetimeInRounds) + 1n) * BigInt(slashingRoundSize) * BigInt(slotDuration)) /
+          BigInt(ethereumSlotDuration),
+    );
+
+    this.logger.trace(
+      `Starting search for slash payload ${payloadAddress} from block ${currentBlockNumber} with earliest block ${earliestBlockNumber}`,
+    );
+    const batchSize = BigInt(settings.logsBatchSize ?? 10000);
+    let toBlock = currentBlockNumber;
+
+    do {
+      const fromBlock = maxBigint(earliestBlockNumber, toBlock - batchSize);
+      this.logger.trace(`Searching for slash payload ${payloadAddress} in blocks ${fromBlock} to ${toBlock}`);
+      const logs = await this.contract.getEvents.SlashPayloadCreated(
+        { payloadAddress: payloadAddress.toString() },
+        { fromBlock, toBlock, strict: true },
+      );
+
+      // We found the payload, return it
+      if (logs.length > 0) {
+        const log = logs[0];
+        const { validators, amounts, offenses } = log.args;
+
+        // Convert the data to our internal types
+        const slashes: ValidatorSlash[] = validators!.map((validator, i) => ({
+          validator: EthAddress.fromString(validator),
+          amount: amounts![i],
+          offenses: offenses![i].map(unpackValidatorSlashOffense),
+        }));
+
+        // Get the timestamp from the block
+        const block = await this.client.getBlock({ blockNumber: log.blockNumber, includeTransactions: false });
+
+        return { address: payloadAddress, slashes, timestamp: block.timestamp };
+      }
+
+      // If not found, we go back one batch
+      toBlock -= batchSize;
+    } while (toBlock > earliestBlockNumber);
+
+    return undefined;
+  }
+
+  public async getAddressAndIsDeployed(
+    slashes: ValidatorSlash[],
+  ): Promise<{ address: EthAddress; salt: Hex; isDeployed: boolean }> {
+    const sortedSlashes = this.sortSlashes(slashes);
+    const [address, salt, isDeployed] = await this.contract.read.getAddressAndIsDeployed([
+      sortedSlashes.map(s => s.validator.toString()),
+      sortedSlashes.map(s => s.amount),
+      sortedSlashes.map(s => s.offenses.map(packValidatorSlashOffense)),
+    ]);
+    return { address: EthAddress.fromString(address), salt, isDeployed };
+  }
+
+  private sortSlashes(slashes: ValidatorSlash[]): ValidatorSlash[] {
+    const offenseSorter = (a: ValidatorSlashOffense, b: ValidatorSlashOffense) => {
+      return a.epochOrSlot === b.epochOrSlot ? a.offenseType - b.offenseType : Number(a.epochOrSlot - b.epochOrSlot);
+    };
+    return [...slashes]
+      .map(slash => ({ ...slash, offenses: [...slash.offenses].sort(offenseSorter) }))
+      .sort((a, b) => a.validator.toString().localeCompare(b.validator.toString()));
+  }
+}
+
+export function packValidatorSlashOffense(offense: ValidatorSlashOffense): bigint {
+  const offenseId = OffenseToBigInt[offense.offenseType];
+  if (offenseId > (1 << 8) - 1) {
+    throw new Error(`Offense type ${offense.offenseType} cannot be packed into 8 bits`);
+  }
+  return (offenseId << 120n) + offense.epochOrSlot;
+}
+
+export function unpackValidatorSlashOffense(packed: bigint): ValidatorSlashOffense {
+  const offenseId = (packed >> 120n) & 0xffn;
+  const epochOrSlot = packed & ((1n << 120n) - 1n);
+  const offenseType = bigIntToOffense(offenseId);
+  return { epochOrSlot, offenseType };
+}

package/src/slashing/empire.ts

@@ -0,0 +1,100 @@
+import { getRoundForSlot, getRoundsForEpoch } from './helpers.js';
+import type { Offense, OffenseIdentifier, SlashPayload, SlashPayloadRound, ValidatorSlash } from './types.js';
+import { OffenseType } from './types.js';
+
+/**
+ * Returns true if the offense is uncontroversial as in it can be verified via L1 data alone,
+ * and does not depend on the local view of the node of the L2 p2p network.
+ * @param offense - The offense type to check
+ */
+export function isOffenseUncontroversial(offense: OffenseType): boolean {
+  return (
+    offense === OffenseType.PROPOSED_INSUFFICIENT_ATTESTATIONS ||
+    offense === OffenseType.PROPOSED_INCORRECT_ATTESTATIONS ||
+    offense === OffenseType.ATTESTED_DESCENDANT_OF_INVALID
+  );
+}
+
+/** Extracts offense identifiers (validator, epoch, offense type) from an Empire-based SlashPayload */
+export function getOffenseIdentifiersFromPayload(payload: SlashPayload | SlashPayloadRound): OffenseIdentifier[] {
+  return payload.slashes.flatMap((slash: ValidatorSlash) =>
+    slash.offenses.map(o => ({
+      validator: slash.validator,
+      offenseType: o.offenseType,
+      epochOrSlot: o.epochOrSlot,
+    })),
+  );
+}
+
+/** Creates ValidatorSlashes used to create an Empire-based SlashPayload from a set of Offenses */
+export function offensesToValidatorSlash(offenses: Offense[]): ValidatorSlash[] {
+  return offenses.map(offense => ({
+    validator: offense.validator,
+    amount: offense.amount,
+    offenses: [{ epochOrSlot: offense.epochOrSlot, offenseType: offense.offenseType }],
+  }));
+}
+
+/**
+ * Sorts offense data by:
+ * - Uncontroversial offenses first
+ * - Slash amount (descending)
+ * - Epoch or slot (ascending, ie oldest first)
+ * - Validator address (ascending)
+ * - Offense type (descending)
+ */
+export function offenseDataComparator(a: Offense, b: Offense): number {
+  return (
+    Number(isOffenseUncontroversial(b.offenseType)) - Number(isOffenseUncontroversial(a.offenseType)) ||
+    Number(b.amount - a.amount) ||
+    Number(a.epochOrSlot - b.epochOrSlot) ||
+    a.validator.toString().localeCompare(b.validator.toString()) ||
+    Number(b.offenseType) - Number(a.offenseType)
+  );
+}
+
+/**
+ * Returns the first round in which the offense is eligible for being included in an Empire-based slash payload.
+ * Should be equal to to the first round that starts strictly after the offense becomes detectable.
+ */
+export function getFirstEligibleRoundForOffense(
+  offense: OffenseIdentifier,
+  constants: { slashingRoundSize: number; epochDuration: number; proofSubmissionEpochs: number },
+): bigint {
+  // TODO(palla/slash): Check for off-by-ones
+  switch (offense.offenseType) {
+    // Inactivity is detected at the end of the epoch, so we flag it as detected in the first fresh round for the next epoch
+    case OffenseType.INACTIVITY: {
+      const epoch = offense.epochOrSlot;
+      const detectedEpoch = epoch + 1n;
+      return getRoundsForEpoch(detectedEpoch, constants)[0] + 1n;
+    }
+    // These offenses are detected once an epoch is pruned, which happens after the proof submission window
+    case OffenseType.VALID_EPOCH_PRUNED:
+    case OffenseType.DATA_WITHHOLDING: {
+      // TODO(palla/slash): Check for off-by-ones especially here
+      const epoch = offense.epochOrSlot;
+      const detectedEpoch = epoch + BigInt(constants.proofSubmissionEpochs);
+      return getRoundsForEpoch(detectedEpoch, constants)[0] + 1n;
+    }
+    // These offenses are detected immediately in the slot they occur, so we assume they are detected in the first round for the following slot
+    case OffenseType.PROPOSED_INSUFFICIENT_ATTESTATIONS:
+    case OffenseType.PROPOSED_INCORRECT_ATTESTATIONS:
+    case OffenseType.ATTESTED_DESCENDANT_OF_INVALID:
+    case OffenseType.BROADCASTED_INVALID_BLOCK_PROPOSAL: {
+      const slot = offense.epochOrSlot;
+      const detectedSlot = slot + 1n;
+      return getRoundForSlot(detectedSlot, constants).round + 1n;
+    }
+    // Assume these are epoch-based offenses, even though we should never have to process these
+    case OffenseType.UNKNOWN: {
+      const epoch = offense.epochOrSlot;
+      const detectedEpoch = epoch + 1n;
+      return getRoundsForEpoch(detectedEpoch, constants)[0] + 1n;
+    }
+    default: {
+      const _: never = offense.offenseType;
+      throw new Error(`Unknown offense type: ${offense.offenseType}`);
+    }
+  }
+}

package/src/slashing/helpers.ts

@@ -0,0 +1,87 @@
+import { type L1RollupConstants, getEpochAtSlot, getSlotRangeForEpoch } from '../epoch-helpers/index.js';
+import { type Offense, OffenseType } from './types.js';
+
+/** Returns the voting round number and voting slot within the round for a given L2 slot. */
+export function getRoundForSlot(
+  slot: bigint,
+  constants: { slashingRoundSize: number },
+): { round: bigint; votingSlot: bigint } {
+  const roundSize = BigInt(constants.slashingRoundSize);
+  const round = slot / roundSize;
+  const votingSlot = slot % roundSize;
+  return { round, votingSlot };
+}
+
+/** Returns the voting round(s) lower and upper bounds (inclusive) covered by the given epoch */
+export function getRoundsForEpoch(
+  epoch: bigint,
+  constants: { slashingRoundSize: number; epochDuration: number },
+): [bigint, bigint] {
+  const [start, end] = getSlotRangeForEpoch(epoch, constants);
+  const startRound = getRoundForSlot(start, constants).round;
+  const endRound = getRoundForSlot(end, constants).round;
+  return [startRound, endRound];
+}
+
+/** Returns the epochs spanned during a given slashing round */
+export function getEpochsForRound(
+  round: bigint,
+  constants: { slashingRoundSize: number; epochDuration: number },
+): bigint[] {
+  const epochs: bigint[] = [];
+  const firstSlot = round * BigInt(constants.slashingRoundSize);
+  const lastSlot = firstSlot + BigInt(constants.slashingRoundSize) - 1n;
+  const startEpoch = getEpochAtSlot(firstSlot, constants);
+  const endEpoch = getEpochAtSlot(lastSlot, constants);
+  for (let epoch = startEpoch; epoch <= endEpoch; epoch++) {
+    epochs.push(epoch);
+  }
+  return epochs;
+}
+
+/** Returns whether the `epochOrSlot` field for an offense references an epoch or a slot */
+export function getTimeUnitForOffense(offense: OffenseType): 'epoch' | 'slot' {
+  switch (offense) {
+    case OffenseType.ATTESTED_DESCENDANT_OF_INVALID:
+    case OffenseType.BROADCASTED_INVALID_BLOCK_PROPOSAL:
+    case OffenseType.PROPOSED_INCORRECT_ATTESTATIONS:
+    case OffenseType.PROPOSED_INSUFFICIENT_ATTESTATIONS:
+      return 'slot';
+    case OffenseType.INACTIVITY:
+    case OffenseType.DATA_WITHHOLDING:
+    case OffenseType.UNKNOWN:
+    case OffenseType.VALID_EPOCH_PRUNED:
+      return 'epoch';
+    default: {
+      const _: never = offense;
+      throw new Error(`Unknown offense type: ${offense}`);
+    }
+  }
+}
+
+/** Returns the slot for a given offense. If the offense references an epoch, returns the first slot of the epoch. */
+export function getSlotForOffense(
+  offense: Pick<Offense, 'epochOrSlot' | 'offenseType'>,
+  constants: Pick<L1RollupConstants, 'epochDuration'>,
+): bigint {
+  const { epochOrSlot, offenseType } = offense;
+  return getTimeUnitForOffense(offenseType) === 'epoch' ? epochOrSlot * BigInt(constants.epochDuration) : epochOrSlot;
+}
+
+/** Returns the epoch for a given offense. */
+export function getEpochForOffense(
+  offense: Pick<Offense, 'epochOrSlot' | 'offenseType'>,
+  constants: Pick<L1RollupConstants, 'epochDuration'>,
+): bigint {
+  const { epochOrSlot, offenseType } = offense;
+  return getTimeUnitForOffense(offenseType) === 'epoch' ? epochOrSlot : epochOrSlot / BigInt(constants.epochDuration);
+}
+
+/** Returns the slashing round in which a given offense occurred. */
+export function getRoundForOffense(
+  offense: Pick<Offense, 'epochOrSlot' | 'offenseType'>,
+  constants: { slashingRoundSize: number; epochDuration: number },
+): bigint {
+  const slot = getSlotForOffense(offense, constants);
+  return getRoundForSlot(slot, constants).round;
+}