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

package/src/slashing/index.ts

@@ -1,74 +1,6 @@
-import type { EthAddress } from '@aztec/foundation/eth-address';
-
-import { z } from 'zod';
-
-import { type ZodFor, schemas } from '../schemas/index.js';
-
-export enum Offense {
-  UNKNOWN = 0,
-  DATA_WITHHOLDING = 1,
-  VALID_EPOCH_PRUNED = 2,
-  INACTIVITY = 3,
-  /** A proposer sent an invalid block proposal over the p2p network to the committee */
-  BROADCASTED_INVALID_BLOCK_PROPOSAL = 4,
-  /** A proposer pushed to L1 a block with insufficient committee attestations */
-  PROPOSED_INSUFFICIENT_ATTESTATIONS = 5,
-  /** A proposer pushed to L1 a block with incorrect committee attestations (ie signature from a non-committee member) */
-  PROPOSED_INCORRECT_ATTESTATIONS = 6,
-  /** A committee member attested to a block that was built as a descendent of an invalid block (as in a block with invalid attestations) */
-  ATTESTED_DESCENDANT_OF_INVALID = 7,
-}
-
-export const OffenseSchema = z.nativeEnum(Offense);
-
-export type MonitoredSlashPayload = {
-  payloadAddress: EthAddress;
-  validators: readonly EthAddress[];
-  amounts: readonly bigint[];
-  offenses: readonly Offense[];
-  observedAtSeconds: number;
-  totalAmount: bigint;
-};
-
-export const MonitoredSlashPayloadSchema = z.object({
-  payloadAddress: schemas.EthAddress,
-  validators: z.array(schemas.EthAddress),
-  amounts: z.array(schemas.BigInt),
-  offenses: z.array(OffenseSchema),
-  observedAtSeconds: z.number(),
-  totalAmount: schemas.BigInt,
-}) satisfies ZodFor<MonitoredSlashPayload>;
-
-export const OffenseToBigInt: Record<Offense, bigint> = {
-  [Offense.UNKNOWN]: 0n,
-  [Offense.DATA_WITHHOLDING]: 1n,
-  [Offense.VALID_EPOCH_PRUNED]: 2n,
-  [Offense.INACTIVITY]: 3n,
-  [Offense.BROADCASTED_INVALID_BLOCK_PROPOSAL]: 4n,
-  [Offense.PROPOSED_INSUFFICIENT_ATTESTATIONS]: 5n,
-  [Offense.PROPOSED_INCORRECT_ATTESTATIONS]: 6n,
-  [Offense.ATTESTED_DESCENDANT_OF_INVALID]: 7n,
-};
-
-export function bigIntToOffense(offense: bigint): Offense {
-  switch (offense) {
-    case 0n:
-      return Offense.UNKNOWN;
-    case 1n:
-      return Offense.DATA_WITHHOLDING;
-    case 2n:
-      return Offense.VALID_EPOCH_PRUNED;
-    case 3n:
-      return Offense.INACTIVITY;
-    case 4n:
-      return Offense.BROADCASTED_INVALID_BLOCK_PROPOSAL;
-    case 5n:
-      return Offense.PROPOSED_INSUFFICIENT_ATTESTATIONS;
-    case 6n:
-      return Offense.PROPOSED_INCORRECT_ATTESTATIONS;
-    case 7n:
-      return Offense.ATTESTED_DESCENDANT_OF_INVALID;
-    default:
-      throw new Error(`Unknown offense: ${offense}`);
-  }
-}
+export * from './types.js';
+export * from './interfaces.js';
+export * from './helpers.js';
+export * from './empire.js';
+export * from './tally.js';
+export * from './serialization.js';

package/src/slashing/interfaces.ts

@@ -0,0 +1,11 @@
+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: bigint): Promise<ProposerSlashAction[]>;
+}

package/src/slashing/serialization.ts

@@ -0,0 +1,103 @@
+import { times } from '@aztec/foundation/collection';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { BufferReader, bigintToUInt64BE, bigintToUInt128BE, serializeToBuffer } from '@aztec/foundation/serialize';
+
+import type {
+  Offense,
+  OffenseType,
+  SlashPayload,
+  SlashPayloadRound,
+  ValidatorSlash,
+  ValidatorSlashOffense,
+} from './types.js';
+
+export function serializeOffense(offense: Offense): Buffer {
+  return serializeToBuffer(
+    offense.validator,
+    bigintToUInt128BE(offense.amount),
+    offense.offenseType,
+    bigintToUInt64BE(offense.epochOrSlot),
+  );
+}
+
+export function deserializeOffense(buffer: Buffer): Offense {
+  const reader = BufferReader.asReader(buffer);
+  const validator = reader.readObject(EthAddress);
+  const amount = reader.readUInt128();
+  const offense = reader.readNumber() as OffenseType;
+  const epochOrSlot = reader.readUInt64();
+
+  return { validator, amount, offenseType: offense, epochOrSlot };
+}
+
+function serializeValidatorSlashOffense(offense: ValidatorSlashOffense): Buffer {
+  return serializeToBuffer(bigintToUInt64BE(offense.epochOrSlot), offense.offenseType);
+}
+
+function deserializeValidatorSlashOffense(buffer: Buffer | BufferReader): ValidatorSlashOffense {
+  const reader = BufferReader.asReader(buffer);
+  return {
+    epochOrSlot: reader.readUInt64(),
+    offenseType: reader.readNumber() as OffenseType,
+  };
+}
+
+function serializeValidatorSlash(slash: ValidatorSlash): Buffer {
+  return serializeToBuffer(
+    slash.validator,
+    bigintToUInt128BE(slash.amount),
+    slash.offenses.length,
+    slash.offenses.map(serializeValidatorSlashOffense),
+  );
+}
+
+function deserializeValidatorSlash(buffer: Buffer | BufferReader): ValidatorSlash {
+  const reader = BufferReader.asReader(buffer);
+  const validator = reader.readObject(EthAddress);
+  const amount = reader.readUInt128();
+  const offensesCount = reader.readNumber();
+  const offenses = times(offensesCount, () => deserializeValidatorSlashOffense(reader));
+
+  return { validator, amount, offenses };
+}
+
+export function serializeSlashPayload(payload: SlashPayload): Buffer {
+  return serializeToBuffer(
+    payload.address,
+    payload.slashes.length,
+    payload.slashes.map(serializeValidatorSlash),
+    bigintToUInt64BE(payload.timestamp),
+  );
+}
+
+export function deserializeSlashPayload(buffer: Buffer): SlashPayload {
+  const reader = BufferReader.asReader(buffer);
+  const address = reader.readObject(EthAddress);
+  const slashesCount = reader.readNumber();
+  const slashes = times(slashesCount, () => deserializeValidatorSlash(reader));
+  const timestamp = reader.readUInt64();
+  return { address, slashes, timestamp };
+}
+
+export function serializeSlashPayloadRound(payload: SlashPayloadRound): Buffer {
+  return serializeToBuffer(
+    payload.address,
+    payload.slashes.length,
+    payload.slashes.map(serializeValidatorSlash),
+    bigintToUInt64BE(payload.timestamp),
+    Number(payload.votes),
+    bigintToUInt64BE(payload.round),
+  );
+}
+
+export function deserializeSlashPayloadRound(buffer: Buffer): SlashPayloadRound {
+  const reader = BufferReader.asReader(buffer);
+  const address = reader.readObject(EthAddress);
+  const slashesCount = reader.readNumber();
+  const slashes = times(slashesCount, () => deserializeValidatorSlash(reader));
+  const timestamp = reader.readUInt64();
+  const votes = BigInt(reader.readNumber());
+  const round = reader.readUInt64();
+
+  return { address, slashes, timestamp, votes, round };
+}

package/src/slashing/tally.ts

@@ -0,0 +1,51 @@
+import { minBigint, sumBigint } from '@aztec/foundation/bigint';
+import type { EthAddress } from '@aztec/foundation/eth-address';
+
+import type { Offense, ValidatorSlashVote } from './types.js';
+
+/** How many slashing units a validator can be slashed in consensus-based slashing */
+const MAX_SLASH_UNITS_PER_VALIDATOR = 3n;
+
+/**
+ * Creates a consensus-slash vote for a given set of committees based on a set of Offenses
+ * @returns Array of ValidatorSlashVote, where each vote is how many slash units the validator in that position should be slashed
+ */
+export function getSlashConsensusVotesFromOffenses(
+  offenses: Offense[],
+  committees: EthAddress[][],
+  settings: { slashingUnit: bigint },
+): ValidatorSlashVote[] {
+  const { slashingUnit } = settings;
+  const slashed: Set<string> = new Set();
+  const votes = committees.flatMap(committee =>
+    committee.map(validator => {
+      if (slashed.has(validator.toString())) {
+        return 0; // Already voted for slashing this validator
+      }
+      const validatorOffenses = offenses.filter(o => o.validator.equals(validator));
+      const slashAmount = sumBigint(validatorOffenses.map(o => o.amount));
+      const slashUnits = minBigint(slashAmount / slashingUnit, MAX_SLASH_UNITS_PER_VALIDATOR);
+      slashed.add(validator.toString());
+      return Number(slashUnits);
+    }),
+  );
+  return votes;
+}
+
+/**
+ * Encodes a set of slash votes into a Buffer for use in a consensus slashing vote transaction.
+ * Each vote is represented as a 2-bit value, which represents how many slashing units the validator should be slashed.
+ * @param votes - The array of slash votes to encode
+ * @returns A Buffer containing the encoded slash votes
+ */
+export function encodeSlashConsensusVotes(votes: ValidatorSlashVote[]): Buffer {
+  if (votes.length % 4 !== 0) {
+    throw new Error('Votes array must have a length that is a multiple of 4');
+  }
+  const buffer = Buffer.alloc(votes.length / 4);
+  for (let i = 0; i < votes.length; i += 4) {
+    const voteByte = (votes[i] << 6) | (votes[i + 1] << 4) | (votes[i + 2] << 2) | votes[i + 3]; // Combine four votes into one byte
+    buffer.writeUInt8(voteByte, i / 4);
+  }
+  return buffer;
+}

package/src/slashing/types.ts

@@ -0,0 +1,129 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+
+import { z } from 'zod';
+
+import { type ZodFor, schemas } from '../schemas/index.js';
+
+export enum OffenseType {
+  UNKNOWN = 0,
+  /** The data for proving an epoch was not publicly available, we slash its committee */
+  DATA_WITHHOLDING = 1,
+  /** An epoch was not successfully proven in time, we slash its committee */
+  VALID_EPOCH_PRUNED = 2,
+  /** A proposer failed to attest or propose during an epoch according to the Sentinel */
+  INACTIVITY = 3,
+  /** A proposer sent an invalid block proposal over the p2p network to the committee */
+  BROADCASTED_INVALID_BLOCK_PROPOSAL = 4,
+  /** A proposer pushed to L1 a block with insufficient committee attestations */
+  PROPOSED_INSUFFICIENT_ATTESTATIONS = 5,
+  /** A proposer pushed to L1 a block with incorrect committee attestations (ie signature from a non-committee member) */
+  PROPOSED_INCORRECT_ATTESTATIONS = 6,
+  /** A committee member attested to a block that was built as a descendent of an invalid block (as in a block with invalid attestations) */
+  ATTESTED_DESCENDANT_OF_INVALID = 7,
+}
+
+export const OffenseTypeSchema = z.nativeEnum(OffenseType);
+
+export const OffenseToBigInt: Record<OffenseType, bigint> = {
+  [OffenseType.UNKNOWN]: 0n,
+  [OffenseType.DATA_WITHHOLDING]: 1n,
+  [OffenseType.VALID_EPOCH_PRUNED]: 2n,
+  [OffenseType.INACTIVITY]: 3n,
+  [OffenseType.BROADCASTED_INVALID_BLOCK_PROPOSAL]: 4n,
+  [OffenseType.PROPOSED_INSUFFICIENT_ATTESTATIONS]: 5n,
+  [OffenseType.PROPOSED_INCORRECT_ATTESTATIONS]: 6n,
+  [OffenseType.ATTESTED_DESCENDANT_OF_INVALID]: 7n,
+};
+
+export function bigIntToOffense(offense: bigint): OffenseType {
+  switch (offense) {
+    case 0n:
+      return OffenseType.UNKNOWN;
+    case 1n:
+      return OffenseType.DATA_WITHHOLDING;
+    case 2n:
+      return OffenseType.VALID_EPOCH_PRUNED;
+    case 3n:
+      return OffenseType.INACTIVITY;
+    case 4n:
+      return OffenseType.BROADCASTED_INVALID_BLOCK_PROPOSAL;
+    case 5n:
+      return OffenseType.PROPOSED_INSUFFICIENT_ATTESTATIONS;
+    case 6n:
+      return OffenseType.PROPOSED_INCORRECT_ATTESTATIONS;
+    case 7n:
+      return OffenseType.ATTESTED_DESCENDANT_OF_INVALID;
+    default:
+      throw new Error(`Unknown offense: ${offense}`);
+  }
+}
+
+export type Offense = {
+  validator: EthAddress;
+  amount: bigint;
+  offenseType: OffenseType;
+  epochOrSlot: bigint;
+};
+
+export type OffenseIdentifier = Pick<Offense, 'validator' | 'offenseType' | 'epochOrSlot'>;
+
+export const OffenseSchema = z.object({
+  validator: schemas.EthAddress,
+  amount: schemas.BigInt,
+  offenseType: OffenseTypeSchema,
+  epochOrSlot: schemas.BigInt,
+}) satisfies ZodFor<Offense>;
+
+/** Offense by a validator in the context of a slash payload */
+export type ValidatorSlashOffense = {
+  epochOrSlot: bigint;
+  offenseType: OffenseType;
+};
+
+/** Slashed amount and total offenses by a validator in the context of a slash payload */
+export type ValidatorSlash = {
+  validator: EthAddress;
+  amount: bigint;
+  offenses: ValidatorSlashOffense[];
+};
+
+/** Slash payload as published by the empire slash proposer */
+export type SlashPayload = {
+  address: EthAddress;
+  slashes: ValidatorSlash[];
+  timestamp: bigint;
+};
+
+/** Slash payload with round information from empire slash proposer */
+export type SlashPayloadRound = SlashPayload & { votes: bigint; round: 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 })),
+    }),
+  ),
+}) satisfies ZodFor<SlashPayloadRound>;
+
+/** Votes for a validator slash in the consensus slash proposer */
+export type ValidatorSlashVote = number;
+
+export type ProposerSlashAction =
+  /** Create a new slash payload on an empire-based slash proposer */
+  | { type: 'create-empire-payload'; data: ValidatorSlash[] }
+  /** Vote for a slashing payload on an empire-based slash proposer */
+  | { type: 'vote-empire-payload'; payload: EthAddress }
+  /** Execute a slashing payload on an empire-based slash proposer */
+  | { type: 'execute-empire-payload'; round: bigint }
+  /** Vote for offenses on a consensus slashing proposer */
+  | { type: 'vote-offenses'; votes: ValidatorSlashVote[]; committees: EthAddress[][]; round: bigint }
+  /** Execute a slashing round on a consensus slashing proposer */
+  | { type: 'execute-slash'; committees: EthAddress[][]; round: bigint };
+
+export type ProposerSlashActionType = ProposerSlashAction['type'];

package/src/stats/stats.ts

@@ -202,9 +202,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;