@aztec/stdlib 0.0.0-test.1 → 0.0.1-commit.017a351

package/src/rollup/root_rollup_public_inputs.ts

@@ -0,0 +1,108 @@
+import { FinalBlobAccumulator } from '@aztec/blob-lib/types';
+import { MAX_CHECKPOINTS_PER_EPOCH } from '@aztec/constants';
+import { makeTuple } from '@aztec/foundation/array';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { bufferSchemaFor } from '@aztec/foundation/schemas';
+import { BufferReader, type Tuple, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
+import { bufferToHex, hexToBuffer } from '@aztec/foundation/string';
+import type { FieldsOf } from '@aztec/foundation/types';
+
+import { FeeRecipient } from './checkpoint_rollup_public_inputs.js';
+import { EpochConstantData } from './epoch_constant_data.js';
+
+/**
+ * Represents public inputs of the root rollup circuit.
+ *
+ * NOTE: in practice, we'll hash all of this up into a single public input, for cheap onchain verification.
+ */
+export class RootRollupPublicInputs {
+  constructor(
+    /** Root of the archive tree before this rollup is processed */
+    public previousArchiveRoot: Fr,
+    /** Root of the archive tree after this rollup is processed */
+    public endArchiveRoot: Fr,
+    /**
+     * Root of the balanced merkle tree consisting of the out hashes of all checkpoints in this epoch.
+     * The out hash of the first checkpoint in the epoch is inserted at index 0, the second at index 1, and so on.
+     */
+    public outHash: Fr,
+    /** Hashes of checkpoint headers for this rollup. */
+    public checkpointHeaderHashes: Tuple<Fr, typeof MAX_CHECKPOINTS_PER_EPOCH>,
+    public fees: Tuple<FeeRecipient, typeof MAX_CHECKPOINTS_PER_EPOCH>,
+    public constants: EpochConstantData,
+    public blobPublicInputs: FinalBlobAccumulator,
+  ) {}
+
+  static getFields(fields: FieldsOf<RootRollupPublicInputs>) {
+    return [
+      fields.previousArchiveRoot,
+      fields.endArchiveRoot,
+      fields.outHash,
+      fields.checkpointHeaderHashes,
+      fields.fees,
+      fields.constants,
+      fields.blobPublicInputs,
+    ] as const;
+  }
+
+  toBuffer() {
+    return serializeToBuffer(...RootRollupPublicInputs.getFields(this));
+  }
+
+  toFields(): Fr[] {
+    return serializeToFields(...RootRollupPublicInputs.getFields(this));
+  }
+
+  static from(fields: FieldsOf<RootRollupPublicInputs>): RootRollupPublicInputs {
+    return new RootRollupPublicInputs(...RootRollupPublicInputs.getFields(fields));
+  }
+
+  /**
+   * Deserializes a buffer into a `RootRollupPublicInputs` object.
+   * @param buffer - The buffer to deserialize.
+   * @returns The deserialized `RootRollupPublicInputs` object.
+   */
+  public static fromBuffer(buffer: Buffer | BufferReader): RootRollupPublicInputs {
+    const reader = BufferReader.asReader(buffer);
+    return new RootRollupPublicInputs(
+      Fr.fromBuffer(reader),
+      Fr.fromBuffer(reader),
+      Fr.fromBuffer(reader),
+      reader.readArray(MAX_CHECKPOINTS_PER_EPOCH, Fr),
+      reader.readArray(MAX_CHECKPOINTS_PER_EPOCH, FeeRecipient),
+      EpochConstantData.fromBuffer(reader),
+      reader.readObject(FinalBlobAccumulator),
+    );
+  }
+
+  toString() {
+    return bufferToHex(this.toBuffer());
+  }
+
+  static fromString(str: string) {
+    return RootRollupPublicInputs.fromBuffer(hexToBuffer(str));
+  }
+
+  /** Returns a representation for JSON serialization. */
+  toJSON() {
+    return this.toBuffer();
+  }
+
+  /** Creates an instance from a string. */
+  static get schema() {
+    return bufferSchemaFor(RootRollupPublicInputs);
+  }
+
+  /** Creates a random instance. Used for testing only - will not prove/verify. */
+  static random() {
+    return new RootRollupPublicInputs(
+      Fr.random(),
+      Fr.random(),
+      Fr.random(),
+      makeTuple(MAX_CHECKPOINTS_PER_EPOCH, Fr.random),
+      makeTuple(MAX_CHECKPOINTS_PER_EPOCH, FeeRecipient.random),
+      new EpochConstantData(Fr.random(), Fr.random(), Fr.random(), Fr.random(), Fr.random()),
+      FinalBlobAccumulator.random(),
+    );
+  }
+}

package/src/rollup/tree_snapshot_diff_hints.ts

@@ -0,0 +1,111 @@
+import {
+  MAX_NULLIFIERS_PER_TX,
+  NOTE_HASH_SUBTREE_ROOT_SIBLING_PATH_LENGTH,
+  NULLIFIER_SUBTREE_ROOT_SIBLING_PATH_LENGTH,
+  NULLIFIER_TREE_HEIGHT,
+  PUBLIC_DATA_TREE_HEIGHT,
+} from '@aztec/constants';
+import { makeTuple } from '@aztec/foundation/array';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { BufferReader, type Tuple, serializeToBuffer } from '@aztec/foundation/serialize';
+import { MembershipWitness } from '@aztec/foundation/trees';
+import type { FieldsOf } from '@aztec/foundation/types';
+
+import { NullifierLeafPreimage } from '../trees/index.js';
+
+/**
+ * Hints used while proving state diff validity for the private base rollup.
+ */
+export class TreeSnapshotDiffHints {
+  constructor(
+    /**
+     * Sibling path "pointing to" where the new note hash subtree should be inserted into the note hash tree.
+     */
+    public noteHashSubtreeRootSiblingPath: Tuple<Fr, typeof NOTE_HASH_SUBTREE_ROOT_SIBLING_PATH_LENGTH>,
+    /**
+     * The nullifiers which need to be updated to perform the batch insertion of the new nullifiers.
+     * See `StandardIndexedTree.batchInsert` function for more details.
+     */
+    public nullifierPredecessorPreimages: Tuple<NullifierLeafPreimage, typeof MAX_NULLIFIERS_PER_TX>,
+    /**
+     * Membership witnesses for the nullifiers which need to be updated to perform the batch insertion of the new
+     * nullifiers.
+     */
+    public nullifierPredecessorMembershipWitnesses: Tuple<
+      MembershipWitness<typeof NULLIFIER_TREE_HEIGHT>,
+      typeof MAX_NULLIFIERS_PER_TX
+    >,
+    /**
+     * The nullifiers to be inserted in the tree, sorted high to low.
+     */
+    public sortedNullifiers: Tuple<Fr, typeof MAX_NULLIFIERS_PER_TX>,
+    /**
+     * The indexes of the sorted nullifiers to the original ones.
+     */
+    public sortedNullifierIndexes: Tuple<number, typeof MAX_NULLIFIERS_PER_TX>,
+    /**
+     * Sibling path "pointing to" where the new nullifiers subtree should be inserted into the nullifier tree.
+     */
+    public nullifierSubtreeRootSiblingPath: Tuple<Fr, typeof NULLIFIER_SUBTREE_ROOT_SIBLING_PATH_LENGTH>,
+    /**
+     * Membership witness for the fee payer's balance leaf in the public data tree.
+     */
+    public feePayerBalanceMembershipWitness: MembershipWitness<typeof PUBLIC_DATA_TREE_HEIGHT>,
+  ) {}
+
+  static from(fields: FieldsOf<TreeSnapshotDiffHints>): TreeSnapshotDiffHints {
+    return new TreeSnapshotDiffHints(...TreeSnapshotDiffHints.getFields(fields));
+  }
+
+  static getFields(fields: FieldsOf<TreeSnapshotDiffHints>) {
+    return [
+      fields.noteHashSubtreeRootSiblingPath,
+      fields.nullifierPredecessorPreimages,
+      fields.nullifierPredecessorMembershipWitnesses,
+      fields.sortedNullifiers,
+      fields.sortedNullifierIndexes,
+      fields.nullifierSubtreeRootSiblingPath,
+      fields.feePayerBalanceMembershipWitness,
+    ] as const;
+  }
+
+  /**
+   * Serializes the state diff hints to a buffer.
+   * @returns A buffer of the serialized state diff hints.
+   */
+  toBuffer(): Buffer {
+    return serializeToBuffer(...TreeSnapshotDiffHints.getFields(this));
+  }
+
+  /**
+   * Deserializes the state diff hints from a buffer.
+   * @param buffer - A buffer to deserialize from.
+   * @returns A new TreeSnapshotDiffHints instance.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader): TreeSnapshotDiffHints {
+    const reader = BufferReader.asReader(buffer);
+    return new TreeSnapshotDiffHints(
+      reader.readArray(NOTE_HASH_SUBTREE_ROOT_SIBLING_PATH_LENGTH, Fr),
+      reader.readArray(MAX_NULLIFIERS_PER_TX, NullifierLeafPreimage),
+      reader.readArray(MAX_NULLIFIERS_PER_TX, {
+        fromBuffer: buffer => MembershipWitness.fromBuffer(buffer, NULLIFIER_TREE_HEIGHT),
+      }),
+      reader.readArray(MAX_NULLIFIERS_PER_TX, Fr),
+      reader.readNumbers(MAX_NULLIFIERS_PER_TX),
+      reader.readArray(NULLIFIER_SUBTREE_ROOT_SIBLING_PATH_LENGTH, Fr),
+      MembershipWitness.fromBuffer(reader, PUBLIC_DATA_TREE_HEIGHT),
+    );
+  }
+
+  static empty() {
+    return new TreeSnapshotDiffHints(
+      makeTuple(NOTE_HASH_SUBTREE_ROOT_SIBLING_PATH_LENGTH, Fr.zero),
+      makeTuple(MAX_NULLIFIERS_PER_TX, NullifierLeafPreimage.empty),
+      makeTuple(MAX_NULLIFIERS_PER_TX, () => MembershipWitness.empty(NULLIFIER_TREE_HEIGHT)),
+      makeTuple(MAX_NULLIFIERS_PER_TX, Fr.zero),
+      makeTuple(MAX_NULLIFIERS_PER_TX, () => 0),
+      makeTuple(NULLIFIER_SUBTREE_ROOT_SIBLING_PATH_LENGTH, Fr.zero),
+      MembershipWitness.empty(PUBLIC_DATA_TREE_HEIGHT),
+    );
+  }
+}

package/src/rollup/tx_merge_rollup_private_inputs.ts

@@ -0,0 +1,66 @@
+import { bufferSchemaFor } from '@aztec/foundation/schemas';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { bufferToHex, hexToBuffer } from '@aztec/foundation/string';
+
+import { ProofData, type RollupHonkProofData } from '../proofs/proof_data.js';
+import { TxRollupPublicInputs } from './tx_rollup_public_inputs.js';
+
+/**
+ * Represents inputs of the merge rollup circuit.
+ */
+export class TxMergeRollupPrivateInputs {
+  constructor(
+    /**
+     * Previous rollup data from the 2 merge or base rollup circuits that preceded this merge rollup circuit.
+     */
+    public previousRollups: [RollupHonkProofData<TxRollupPublicInputs>, RollupHonkProofData<TxRollupPublicInputs>],
+  ) {}
+
+  /**
+   * Serializes the inputs to a buffer.
+   * @returns The inputs serialized to a buffer.
+   */
+  toBuffer() {
+    return serializeToBuffer(this.previousRollups);
+  }
+
+  /**
+   * Serializes the inputs to a hex string.
+   * @returns The instance serialized to a hex string.
+   */
+  toString() {
+    return bufferToHex(this.toBuffer());
+  }
+
+  /**
+   * Deserializes the inputs from a buffer.
+   * @param buffer - The buffer to deserialize from.
+   * @returns A new TxMergeRollupPrivateInputs instance.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new TxMergeRollupPrivateInputs([
+      ProofData.fromBuffer(reader, TxRollupPublicInputs),
+      ProofData.fromBuffer(reader, TxRollupPublicInputs),
+    ]);
+  }
+
+  /**
+   * Deserializes the inputs from a hex string.
+   * @param str - A hex string to deserialize from.
+   * @returns A new TxMergeRollupPrivateInputs instance.
+   */
+  static fromString(str: string) {
+    return TxMergeRollupPrivateInputs.fromBuffer(hexToBuffer(str));
+  }
+
+  /** Returns a buffer representation for JSON serialization. */
+  toJSON() {
+    return this.toBuffer();
+  }
+
+  /** Creates an instance from a string. */
+  static get schema() {
+    return bufferSchemaFor(TxMergeRollupPrivateInputs);
+  }
+}

package/src/rollup/tx_rollup_public_inputs.ts

@@ -0,0 +1,138 @@
+import { SpongeBlob } from '@aztec/blob-lib/types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { bufferSchemaFor } from '@aztec/foundation/schemas';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { bufferToHex, hexToBuffer } from '@aztec/foundation/string';
+
+import { PartialStateReference } from '../tx/partial_state_reference.js';
+import { BlockConstantData } from './block_constant_data.js';
+
+/**
+ * Output of the base and merge rollup circuits.
+ */
+export class TxRollupPublicInputs {
+  constructor(
+    /**
+     * Number of txs in this rollup.
+     */
+    public numTxs: number,
+    /**
+     * Data which is forwarded through the rollup circuits unchanged.
+     */
+    public constants: BlockConstantData,
+    /**
+     * Partial state reference at the start of the rollup circuit.
+     */
+    public startTreeSnapshots: PartialStateReference,
+    /**
+     * Partial state reference at the end of the rollup circuit.
+     */
+    public endTreeSnapshots: PartialStateReference,
+    /**
+     * Sponge state to absorb blob inputs at the start of the rollup circuit.
+     */
+    public startSpongeBlob: SpongeBlob,
+    /**
+     * Sponge state to absorb blob inputs at the end of the rollup circuit.
+     */
+    public endSpongeBlob: SpongeBlob,
+    /**
+     * SHA256 hash of L2 to L1 messages. Used to make public inputs constant-sized (to then be opened onchain).
+     * Note: Truncated to 31 bytes to fit in Fr.
+     */
+    public outHash: Fr,
+    /**
+     * The summed `transaction_fee` of the constituent transactions.
+     */
+    public accumulatedFees: Fr,
+    /**
+     * The summed `mana_used` of the constituent transactions.
+     */
+    public accumulatedManaUsed: Fr,
+  ) {}
+
+  /** Returns an empty instance. */
+  static empty() {
+    return new TxRollupPublicInputs(
+      0,
+      BlockConstantData.empty(),
+      PartialStateReference.empty(),
+      PartialStateReference.empty(),
+      SpongeBlob.empty(),
+      SpongeBlob.empty(),
+      Fr.zero(),
+      Fr.zero(),
+      Fr.zero(),
+    );
+  }
+
+  /**
+   * Deserializes from a buffer or reader.
+   * Note: Corresponds to a write in cpp.
+   * @param buffer - Buffer or reader to read from.
+   * @returns The deserialized public inputs.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader): TxRollupPublicInputs {
+    const reader = BufferReader.asReader(buffer);
+    return new TxRollupPublicInputs(
+      reader.readNumber(),
+      reader.readObject(BlockConstantData),
+      reader.readObject(PartialStateReference),
+      reader.readObject(PartialStateReference),
+      reader.readObject(SpongeBlob),
+      reader.readObject(SpongeBlob),
+      Fr.fromBuffer(reader),
+      Fr.fromBuffer(reader),
+      Fr.fromBuffer(reader),
+    );
+  }
+
+  /**
+   * Serialize this as a buffer.
+   * @returns The buffer.
+   */
+  toBuffer() {
+    return serializeToBuffer(
+      this.numTxs,
+      this.constants,
+
+      this.startTreeSnapshots,
+      this.endTreeSnapshots,
+
+      this.startSpongeBlob,
+      this.endSpongeBlob,
+
+      this.outHash,
+
+      this.accumulatedFees,
+      this.accumulatedManaUsed,
+    );
+  }
+
+  /**
+   * Serialize this as a hex string.
+   * @returns - The hex string.
+   */
+  toString() {
+    return bufferToHex(this.toBuffer());
+  }
+
+  /**
+   * Deserializes from a hex string.
+   * @param str - A hex string to deserialize from.
+   * @returns A new TxRollupPublicInputs instance.
+   */
+  static fromString(str: string) {
+    return TxRollupPublicInputs.fromBuffer(hexToBuffer(str));
+  }
+
+  /** Returns a buffer representation for JSON serialization. */
+  toJSON() {
+    return this.toBuffer();
+  }
+
+  /** Creates an instance from a hex string. */
+  static get schema() {
+    return bufferSchemaFor(TxRollupPublicInputs);
+  }
+}

package/src/schemas/schemas.ts

@@ -1,6 +1,8 @@
+import type { EpochNumber, SlotNumber } from '@aztec/foundation/branded-types';
 import type { Buffer32 } from '@aztec/foundation/buffer';
+import type { Fq, Fr } from '@aztec/foundation/curves/bn254';
+import type { Point } from '@aztec/foundation/curves/grumpkin';
 import type { EthAddress } from '@aztec/foundation/eth-address';
-import type { Fq, Fr, Point } from '@aztec/foundation/fields';
 import { type ZodFor, schemas as foundationSchemas } from '@aztec/foundation/schemas';
 
 import { z } from 'zod';
@@ -10,6 +12,7 @@ import { EventSelector } from '../abi/event_selector.js';
 import { FunctionSelector } from '../abi/function_selector.js';
 import { NoteSelector } from '../abi/note_selector.js';
 import { AztecAddress } from '../aztec-address/index.js';
+import { Gas } from '../gas/gas.js';
 
 /**
  * Validation schemas for common types. Every schema must match its toJSON.
@@ -37,6 +40,9 @@ export const schemas = {
   /** Coerces input to UInt32. */
   UInt32: foundationSchemas.UInt32,
 
+  /** Coerces input to UInt64. */
+  UInt64: foundationSchemas.UInt64,
+
   /** Accepts a hex string as a Buffer32 type. */
   Buffer32: foundationSchemas.Buffer32 as ZodFor<Buffer32>,
 
@@ -49,6 +55,9 @@ export const schemas = {
   /** Hex string with an optional 0x prefix which gets removed as part of the parsing. */
   HexString: foundationSchemas.HexString,
 
+  /** Schema for secret config value */
+  SecretValue: foundationSchemas.SecretValue,
+
   /** Accepts a hex string. */
   AztecAddress: AztecAddress.schema,
 
@@ -60,6 +69,19 @@ export const schemas = {
 
   /** Accepts a hex string. */
   EventSelector: EventSelector.schema,
+
+  /** Accepts a number, bigint, or string and coerces to SlotNumber. */
+  SlotNumber: foundationSchemas.SlotNumber as ZodFor<SlotNumber>,
+
+  /** Accepts a number, bigint, or string and coerces to EpochNumber. */
+  EpochNumber: foundationSchemas.EpochNumber as ZodFor<EpochNumber>,
+
+  GasUsed: z.object({
+    totalGas: Gas.schema,
+    teardownGas: Gas.schema,
+    publicGas: Gas.schema,
+    billedGas: Gas.schema,
+  }),
 };
 
 export const AbiDecodedSchema: ZodFor<AbiDecoded> = z.union([
@@ -67,16 +89,25 @@ export const AbiDecodedSchema: ZodFor<AbiDecoded> = z.union([
   z.boolean(),
   schemas.AztecAddress,
   z.array(z.lazy(() => AbiDecodedSchema)),
-  z.record(z.lazy(() => AbiDecodedSchema)),
+  z.record(
+    z.string(),
+    z.lazy(() => AbiDecodedSchema),
+  ),
 ]);
 
+// C++ only supports null values, which we want to convert to undefined.
+export const NullishToUndefined = (schema: ZodFor<any>) => schema.nullish().transform(x => x ?? undefined);
+
 export {
   type ZodFor,
+  zodFor,
   bufferSchema,
   hexSchema,
   hexSchemaFor,
   bufferSchemaFor,
   type ApiSchemaFor,
+  getSchemaParameters,
+  getSchemaReturnType,
   optional,
   mapSchema,
   pickFromSchema,

package/src/slashing/helpers.ts

@@ -0,0 +1,153 @@
+import { EpochNumber, SlotNumber } from '@aztec/foundation/branded-types';
+
+import { type L1RollupConstants, getEpochAtSlot, getSlotRangeForEpoch } from '../epoch-helpers/index.js';
+import type { SlasherConfig } from '../interfaces/slasher.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: SlotNumber,
+  constants: { slashingRoundSize: number },
+): { round: bigint; votingSlot: SlotNumber } {
+  const roundSize = BigInt(constants.slashingRoundSize);
+  const slotBigInt = BigInt(slot);
+  const round = slotBigInt / roundSize;
+  const votingSlot = SlotNumber.fromBigInt(slotBigInt % roundSize);
+  return { round, votingSlot };
+}
+
+/** Returns the voting round(s) lower and upper bounds (inclusive) covered by the given epoch */
+export function getRoundsForEpoch(
+  epoch: EpochNumber,
+  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 },
+): EpochNumber[] {
+  const epochs: EpochNumber[] = [];
+  const firstSlot = SlotNumber.fromBigInt(round * BigInt(constants.slashingRoundSize));
+  const lastSlot = SlotNumber(firstSlot + constants.slashingRoundSize - 1);
+  const startEpoch = getEpochAtSlot(firstSlot, constants);
+  const endEpoch = getEpochAtSlot(lastSlot, constants);
+  for (let epoch = startEpoch; epoch <= endEpoch; epoch = EpochNumber(epoch + 1)) {
+    epochs.push(epoch);
+  }
+  return epochs;
+}
+
+/** Reads the configured penalty for a given offense type from a slasher config struct */
+export function getPenaltyForOffense(
+  offense: OffenseType,
+  config: Pick<
+    SlasherConfig,
+    | 'slashProposeDescendantOfCheckpointWithInvalidAttestationsPenalty'
+    | 'slashBroadcastedInvalidBlockPenalty'
+    | 'slashBroadcastedInvalidCheckpointProposalPenalty'
+    | 'slashDuplicateProposalPenalty'
+    | 'slashDuplicateAttestationPenalty'
+    | 'slashAttestInvalidCheckpointProposalPenalty'
+    | 'slashDataWithholdingPenalty'
+    | 'slashUnknownPenalty'
+    | 'slashInactivityPenalty'
+    | 'slashProposeInvalidAttestationsPenalty'
+  >,
+) {
+  switch (offense) {
+    case OffenseType.DATA_WITHHOLDING:
+      return config.slashDataWithholdingPenalty;
+    case OffenseType.INACTIVITY:
+      return config.slashInactivityPenalty;
+    case OffenseType.PROPOSED_INSUFFICIENT_ATTESTATIONS:
+    case OffenseType.PROPOSED_INCORRECT_ATTESTATIONS:
+      return config.slashProposeInvalidAttestationsPenalty;
+    case OffenseType.PROPOSED_DESCENDANT_OF_CHECKPOINT_WITH_INVALID_ATTESTATIONS:
+      return config.slashProposeDescendantOfCheckpointWithInvalidAttestationsPenalty;
+    case OffenseType.BROADCASTED_INVALID_BLOCK_PROPOSAL:
+      return config.slashBroadcastedInvalidBlockPenalty;
+    case OffenseType.BROADCASTED_INVALID_CHECKPOINT_PROPOSAL:
+      return config.slashBroadcastedInvalidCheckpointProposalPenalty;
+    case OffenseType.DUPLICATE_PROPOSAL:
+      return config.slashDuplicateProposalPenalty;
+    case OffenseType.DUPLICATE_ATTESTATION:
+      return config.slashDuplicateAttestationPenalty;
+    case OffenseType.ATTESTED_TO_INVALID_CHECKPOINT_PROPOSAL:
+      return config.slashAttestInvalidCheckpointProposalPenalty;
+    case OffenseType.UNKNOWN:
+      return config.slashUnknownPenalty;
+    default: {
+      const _exhaustiveCheck: never = offense;
+      throw new Error(`Unknown offense type: ${_exhaustiveCheck}`);
+    }
+  }
+}
+
+/** 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.PROPOSED_DESCENDANT_OF_CHECKPOINT_WITH_INVALID_ATTESTATIONS:
+    case OffenseType.BROADCASTED_INVALID_BLOCK_PROPOSAL:
+    case OffenseType.DATA_WITHHOLDING:
+    case OffenseType.BROADCASTED_INVALID_CHECKPOINT_PROPOSAL:
+    case OffenseType.DUPLICATE_PROPOSAL:
+    case OffenseType.DUPLICATE_ATTESTATION:
+    case OffenseType.ATTESTED_TO_INVALID_CHECKPOINT_PROPOSAL:
+    case OffenseType.PROPOSED_INCORRECT_ATTESTATIONS:
+    case OffenseType.PROPOSED_INSUFFICIENT_ATTESTATIONS:
+      return 'slot';
+    case OffenseType.INACTIVITY:
+    case OffenseType.UNKNOWN:
+      return 'epoch';
+    default: {
+      const _exhaustiveCheck: never = offense;
+      throw new Error(`Unknown offense type: ${_exhaustiveCheck}`);
+    }
+  }
+}
+
+/** 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'>,
+): SlotNumber {
+  const { epochOrSlot, offenseType } = offense;
+  return getTimeUnitForOffense(offenseType) === 'epoch'
+    ? SlotNumber.fromBigInt(epochOrSlot * BigInt(constants.epochDuration))
+    : SlotNumber.fromBigInt(epochOrSlot);
+}
+
+/** Returns the epoch for a given offense. If the offense type or epoch is not defined, returns undefined. */
+export function getEpochForOffense(
+  offense: Pick<Offense, 'epochOrSlot' | 'offenseType'>,
+  constants: Pick<L1RollupConstants, 'epochDuration'>,
+): bigint;
+export function getEpochForOffense(
+  offense: Partial<Pick<Offense, 'epochOrSlot' | 'offenseType'>>,
+  constants: Pick<L1RollupConstants, 'epochDuration'>,
+): bigint | undefined;
+export function getEpochForOffense(
+  offense: Partial<Pick<Offense, 'epochOrSlot' | 'offenseType'>>,
+  constants: Pick<L1RollupConstants, 'epochDuration'>,
+): bigint | undefined {
+  const { epochOrSlot, offenseType } = offense;
+  if (epochOrSlot === undefined || offenseType === undefined) {
+    return undefined;
+  }
+  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;
+}

package/src/slashing/index.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './interfaces.js';
+export * from './helpers.js';
+export * from './votes.js';
+export * from './serialization.js';

package/src/slashing/interfaces.ts

@@ -0,0 +1,13 @@
+import type { SlotNumber } from '@aztec/foundation/branded-types';
+
+import type { ProposerSlashAction } from './types.js';
+
+export interface ProposerSlashActionProvider {
+  /**
+   * Returns the actions to take for the proposer in the current slot.
+   * This can include creating a slash payload or other actions.
+   * @param slotNumber - The current slot number
+   * @returns The actions to take
+   */
+  getProposerActions(slotNumber: SlotNumber): Promise<ProposerSlashAction[]>;
+}