@aztec-labs/stdlib 6.0.0-nightly.20260829

package/src/p2p/index.ts

@@ -0,0 +1,13 @@
+export * from './attestation_utils.js';
+export * from './block_proposal.js';
+export * from './checkpoint_attestation.js';
+export * from './checkpoint_proposal.js';
+export * from './consensus_payload.js';
+export * from './gossipable.js';
+export * from './signature_utils.js';
+export * from './signed_txs.js';
+export * from './topic_type.js';
+export * from './validated_proposal.js';
+export * from './message_validator.js';
+export * from './peer_error.js';
+export * from './constants.js';

package/src/p2p/message_validator.ts

@@ -0,0 +1,22 @@
+import type { PeerErrorSeverity } from './peer_error.js';
+
+/**
+ * Result of validating a P2P message.
+ * - 'accept': Message is valid and should be accepted and processed
+ * - 'ignore': Message should be ignored (not propagated or processed, but sender not penalized)
+ * - 'reject': Message is invalid (rejected and sender penalized)
+ */
+export type ValidationResult =
+  | { result: 'accept' }
+  | { result: 'ignore' }
+  | { result: 'reject'; severity: PeerErrorSeverity };
+
+/**
+ * P2PValidator
+ *
+ * A validator for P2P messages, which returns a ValidationResult indicating
+ * whether to accept, ignore, or reject the message
+ */
+export interface P2PValidator<T> {
+  validate(message: T): Promise<ValidationResult>;
+}

package/src/p2p/peer_error.ts

@@ -0,0 +1,24 @@
+export enum PeerErrorSeverity {
+  /**
+   * Not malicious action, but it must not be tolerated
+   * ~2 occurrences will get the peer banned
+   */
+  LowToleranceError = 'LowToleranceError',
+  /**
+   * Negative action that can be tolerated only sometimes
+   * ~10 occurrences will get the peer banned
+   */
+  MidToleranceError = 'MidToleranceError',
+  /**
+   * Some error that can be tolerated multiple times
+   * ~50 occurrences will get the peer banned
+   */
+  HighToleranceError = 'HighToleranceError',
+}
+
+/** Severities ordered from mildest to harshest. */
+export const PeerErrorSeverityByHarshness = [
+  PeerErrorSeverity.HighToleranceError,
+  PeerErrorSeverity.MidToleranceError,
+  PeerErrorSeverity.LowToleranceError,
+] as const;

package/src/p2p/signature_utils.ts

@@ -0,0 +1,130 @@
+import { Buffer32 } from '@aztec-labs/foundation/buffer';
+import { keccak256 } from '@aztec-labs/foundation/crypto/keccak';
+import { tryRecoverAddress } from '@aztec-labs/foundation/crypto/secp256k1-signer';
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
+import type { Signature } from '@aztec-labs/foundation/eth-signature';
+import { type BufferReader, serializeToBuffer } from '@aztec-labs/foundation/serialize';
+import { type TypedDataDefinition, hashTypedData } from 'viem';
+import { z } from 'zod';
+
+import type { ZodFor } from '../schemas/index.js';
+
+export type CoordinationSignatureType =
+  | 'BlockProposal'
+  | 'CheckpointProposal'
+  | 'CheckpointAttestation'
+  | 'AttestationsAndSigners'
+  | 'SignedTxs';
+
+export type CoordinationSignatureContext = {
+  chainId: number;
+  rollupAddress: EthAddress;
+};
+
+export const EMPTY_COORDINATION_SIGNATURE_CONTEXT: CoordinationSignatureContext = {
+  chainId: 0,
+  rollupAddress: EthAddress.ZERO,
+};
+
+export const coordinationSignatureContextSchema: ZodFor<CoordinationSignatureContext> = z.object({
+  chainId: z.number(),
+  rollupAddress: EthAddress.schema,
+});
+
+export interface Signable {
+  readonly primaryType: CoordinationSignatureType;
+  readonly signatureContext: CoordinationSignatureContext;
+  getPayloadToSign(): Buffer;
+}
+
+export function coordinationSignatureContextEquals(
+  a: CoordinationSignatureContext,
+  b: CoordinationSignatureContext,
+): boolean {
+  return a.chainId === b.chainId && a.rollupAddress.equals(b.rollupAddress);
+}
+
+export function serializeCoordinationSignatureContext(ctx: CoordinationSignatureContext): Buffer {
+  return serializeToBuffer([ctx.chainId, ctx.rollupAddress]);
+}
+
+export function readCoordinationSignatureContext(reader: BufferReader): CoordinationSignatureContext {
+  const chainId = reader.readNumber();
+  const rollupAddress = reader.readObject(EthAddress);
+  return { chainId, rollupAddress };
+}
+
+/**
+ * Returns true if the signable carries a context matching the node's expected context.
+ * Use this at the P2P ingress boundary to reject foreign-chain messages cheaply before
+ * performing any signature recovery.
+ */
+export function hasValidSignatureContext(signable: Signable, expected: CoordinationSignatureContext): boolean {
+  return coordinationSignatureContextEquals(signable.signatureContext, expected);
+}
+
+const COORDINATION_SIGNATURE_NAME = 'Aztec Rollup';
+const COORDINATION_SIGNATURE_VERSION = '1';
+
+const EIP712_DOMAIN_FIELDS = [
+  { name: 'name', type: 'string' },
+  { name: 'version', type: 'string' },
+  { name: 'chainId', type: 'uint256' },
+  { name: 'verifyingContract', type: 'address' },
+] as const;
+
+const COORDINATION_SIGNATURE_TYPES = {
+  EIP712Domain: EIP712_DOMAIN_FIELDS,
+  BlockProposal: [{ name: 'payloadHash', type: 'bytes32' }],
+  CheckpointProposal: [{ name: 'payloadHash', type: 'bytes32' }],
+  CheckpointAttestation: [{ name: 'payloadHash', type: 'bytes32' }],
+  AttestationsAndSigners: [{ name: 'payloadHash', type: 'bytes32' }],
+  SignedTxs: [{ name: 'payloadHash', type: 'bytes32' }],
+} as const;
+
+export function getCoordinationSignatureTypedDataForPayloadHash(
+  payloadHash: Buffer32,
+  type: CoordinationSignatureType,
+  context: CoordinationSignatureContext,
+): TypedDataDefinition {
+  return {
+    domain: {
+      name: COORDINATION_SIGNATURE_NAME,
+      version: COORDINATION_SIGNATURE_VERSION,
+      chainId: context.chainId,
+      verifyingContract: context.rollupAddress.toString() as `0x${string}`,
+    },
+    types: COORDINATION_SIGNATURE_TYPES,
+    primaryType: type,
+    message: {
+      payloadHash: payloadHash.toString() as `0x${string}`,
+    },
+  };
+}
+
+export function getCoordinationSignatureTypedData(signable: Signable): TypedDataDefinition {
+  const payloadHash = getHashedSignaturePayload(signable);
+  return getCoordinationSignatureTypedDataForPayloadHash(payloadHash, signable.primaryType, signable.signatureContext);
+}
+
+export function getHashedSignaturePayloadTypedData(signable: Signable): Buffer32 {
+  return Buffer32.fromString(hashTypedData(getCoordinationSignatureTypedData(signable)));
+}
+
+/**
+ * Recovers the sender of a gossiped coordination message. Deliberately lenient (allowYParityAsV): a
+ * signature whose recovery byte is in yParity form (v ∈ {0, 1}) still resolves to its sender, so the P2P
+ * layer can attribute and accept it and then canonicalize on ingress (CheckpointAttestation.
+ * withNormalizedSignature, A-1351) before it reaches the L1 bundle. This is intentionally looser than
+ * on-chain checkpoint validation (getAttestationInfoFromPayload), which recovers strictly to mirror L1's
+ * ECDSA.recover — do not unify the two. These proposal/attestation signatures are P2P-only and never reach
+ * L1 verbatim, so leniency here cannot leak a non-canonical byte onto L1.
+ */
+export function recoverCoordinationSigner(signable: Signable, signature: Signature): EthAddress | undefined {
+  const digest = getHashedSignaturePayloadTypedData(signable);
+  return tryRecoverAddress(digest, signature, { allowYParityAsV: true });
+}
+
+export function getHashedSignaturePayload(s: Signable): Buffer32 {
+  return Buffer32.fromBuffer(keccak256(s.getPayloadToSign()));
+}

package/src/p2p/signed_txs.ts

@@ -0,0 +1,105 @@
+import type { EthAddress } from '@aztec-labs/foundation/eth-address';
+import { Signature } from '@aztec-labs/foundation/eth-signature';
+import { BufferReader, serializeToBuffer } from '@aztec-labs/foundation/serialize';
+import type { TypedDataDefinition } from 'viem';
+
+import { MAX_TXS_PER_BLOCK } from '../deserialization/index.js';
+import { Tx } from '../tx/tx.js';
+import {
+  type CoordinationSignatureContext,
+  type CoordinationSignatureType,
+  EMPTY_COORDINATION_SIGNATURE_CONTEXT,
+  type Signable,
+  getCoordinationSignatureTypedData,
+  readCoordinationSignatureContext,
+  recoverCoordinationSigner,
+  serializeCoordinationSignatureContext,
+} from './signature_utils.js';
+
+/**
+ * A signed collection of transactions.
+ * The signature is over the transaction objects themselves, providing
+ * data availability guarantees beyond just the transaction hashes.
+ */
+export class SignedTxs implements Signable {
+  readonly primaryType: CoordinationSignatureType = 'SignedTxs';
+
+  private cachedSender: EthAddress | undefined | null = undefined;
+
+  constructor(
+    /** The transactions */
+    public readonly txs: Tx[],
+    /** The proposer's signature over the transactions */
+    public readonly signature: Signature,
+    /** The signing domain (chainId + rollupAddress) the signature is bound to */
+    public readonly signatureContext: CoordinationSignatureContext,
+  ) {}
+
+  getPayloadToSign(): Buffer {
+    return serializeToBuffer([this.txs.length, this.txs]);
+  }
+
+  /**
+   * Lazily evaluate the sender of the signed txs; result is cached.
+   * @returns The sender address, or undefined if signature recovery fails
+   */
+  getSender(): EthAddress | undefined {
+    if (this.cachedSender === undefined) {
+      this.cachedSender = recoverCoordinationSigner(this, this.signature) ?? null;
+    }
+    return this.cachedSender ?? undefined;
+  }
+
+  /**
+   * Create SignedTxs from a typed-data signer function
+   */
+  static async createFromSigner(
+    txs: Tx[],
+    signatureContext: CoordinationSignatureContext,
+    typedDataSigner: (typedData: TypedDataDefinition) => Promise<Signature>,
+  ): Promise<SignedTxs> {
+    const tempSignedTxs = new SignedTxs(txs, Signature.empty(), signatureContext);
+    const typedData = getCoordinationSignatureTypedData(tempSignedTxs);
+    const signature = await typedDataSigner(typedData);
+    return new SignedTxs(txs, signature, signatureContext);
+  }
+
+  toBuffer(): Buffer {
+    return serializeToBuffer([
+      this.txs.length,
+      this.txs,
+      this.signature,
+      serializeCoordinationSignatureContext(this.signatureContext),
+    ]);
+  }
+
+  static fromBuffer(buf: Buffer | BufferReader): SignedTxs {
+    const reader = BufferReader.asReader(buf);
+    const txCount = reader.readNumber();
+    if (txCount > MAX_TXS_PER_BLOCK) {
+      throw new Error(`txs count ${txCount} exceeds maximum ${MAX_TXS_PER_BLOCK}`);
+    }
+    const txs = reader.readArray(txCount, Tx);
+    const signature = reader.readObject(Signature);
+    const signatureContext = readCoordinationSignatureContext(reader);
+    return new SignedTxs(txs, signature, signatureContext);
+  }
+
+  getSize(): number {
+    return (
+      4 /* txs.length */ +
+      this.txs.reduce((acc, tx) => acc + tx.getSize(), 0) +
+      this.signature.getSize() +
+      4 /* chainId */ +
+      20 /* rollupAddress */
+    );
+  }
+
+  static empty(): SignedTxs {
+    return new SignedTxs([], Signature.empty(), EMPTY_COORDINATION_SIGNATURE_CONTEXT);
+  }
+
+  static random(): SignedTxs {
+    return new SignedTxs([Tx.random(), Tx.random()], Signature.random(), EMPTY_COORDINATION_SIGNATURE_CONTEXT);
+  }
+}

package/src/p2p/topic_type.ts

@@ -0,0 +1,58 @@
+/**
+ * Creates the topic channel identifier string from a given topic type
+ */
+export function createTopicString(topicType: TopicType, protocolVersion: string) {
+  return `/aztec/${TopicType[topicType]}/${protocolVersion}`;
+}
+
+/** Extracts the topic type from a topic string */
+export function getTopicFromString(topicStr: string): TopicType | undefined {
+  const parts = topicStr.split('/');
+  if (parts.length < 4 || parts[1] !== 'aztec') {
+    return undefined;
+  }
+  const topic = parts[2];
+  if (Object.values(TopicType).includes(topic as TopicType)) {
+    return topic as TopicType;
+  }
+  return undefined;
+}
+
+export enum TopicType {
+  tx = 'tx',
+  block_proposal = 'block_proposal',
+  checkpoint_proposal = 'checkpoint_proposal',
+  checkpoint_attestation = 'checkpoint_attestation',
+}
+
+/** Returns all gossip topics, optionally filtering out transactions. */
+export function getTopicsForConfig(disableTransactions: boolean) {
+  const topics = [
+    TopicType.tx,
+    TopicType.block_proposal,
+    TopicType.checkpoint_proposal,
+    TopicType.checkpoint_attestation,
+  ];
+  if (disableTransactions) {
+    return topics.filter(topic => topic !== TopicType.tx);
+  }
+  return topics;
+}
+
+/**
+ * Convert the topic string into a set of labels
+ *
+ * In the form:
+ * {
+ *  "/aztec/tx/0.1.0": "tx",
+ *  ...
+ * }
+ */
+export function metricsTopicStrToLabels(protocolVersion: string) {
+  const topicStrToLabel = new Map<string, string>();
+  for (const topic in TopicType) {
+    topicStrToLabel.set(createTopicString(TopicType[topic as keyof typeof TopicType], protocolVersion), topic);
+  }
+
+  return topicStrToLabel;
+}

package/src/p2p/validated_proposal.ts

@@ -0,0 +1,43 @@
+import type { Branded } from '@aztec-labs/foundation/branded-types';
+
+import type { BlockProposal } from './block_proposal.js';
+import type { CheckpointProposalCore } from './checkpoint_proposal.js';
+
+/**
+ * A block proposal that has passed p2p ingress validation.
+ *
+ * Downstream consumers (the validator client's proposal handlers) rely on that validation having already
+ * happened and do not repeat it, so this brand marks the proposals they are allowed to receive. It is a
+ * compile-time marker only: at runtime a `ValidatedBlockProposal` is just a `BlockProposal`.
+ */
+export type ValidatedBlockProposal = Branded<BlockProposal, 'ValidatedBlockProposal'>;
+
+/**
+ * Marks a block proposal as having passed p2p ingress validation.
+ *
+ * May only be called at a point where the gossipsub topic validator has accepted the proposal, which covers
+ * the signature context, the signature itself, the expected proposer for the slot, the index within the
+ * checkpoint, the tx field checks, and the receive-window timeliness check.
+ */
+export function ValidatedBlockProposal(proposal: BlockProposal): ValidatedBlockProposal {
+  return proposal as ValidatedBlockProposal;
+}
+
+/**
+ * A checkpoint proposal (without its last block) that has passed p2p ingress validation.
+ *
+ * Downstream consumers (the validator client's proposal handlers) rely on that validation having already
+ * happened and do not repeat it, so this brand marks the proposals they are allowed to receive. It is a
+ * compile-time marker only: at runtime a `ValidatedCheckpointProposalCore` is just a `CheckpointProposalCore`.
+ */
+export type ValidatedCheckpointProposalCore = Branded<CheckpointProposalCore, 'ValidatedCheckpointProposalCore'>;
+
+/**
+ * Marks a checkpoint proposal as having passed p2p ingress validation.
+ *
+ * May only be called at a point where the gossipsub topic validator has accepted the proposal, which covers
+ * the expected proposer for the slot and the receive-window timeliness check.
+ */
+export function ValidatedCheckpointProposalCore(proposal: CheckpointProposalCore): ValidatedCheckpointProposalCore {
+  return proposal as ValidatedCheckpointProposalCore;
+}

package/src/p2p/wire_compat_fixtures.ts

@@ -0,0 +1,23 @@
+// Golden wire fixtures that pin the exact bytes a peer produces and consumes, so the optional bucket-reference tail
+// added to proposals stays wire compatible: an unset proposal must serialize to these bytes, and decoding these bytes
+// must yield no bucket reference. The block-proposal fixtures were refreshed for the removal of the legacy `inHash`
+// field; the checkpoint-proposal fixture was refreshed for the checkpoint-header format change.
+//
+// Both fixtures come from a deterministic proposal built with:
+//   BlockHeader.empty(), IndexWithinCheckpoint(3), archiveRoot=Fr(99),
+//   txHashes=[TxHash.fromField(Fr(7)), TxHash.fromField(Fr(8))], Signature.empty(), EMPTY_COORDINATION_SIGNATURE_CONTEXT
+// (checkpoint: CheckpointHeader.empty(), archive=Fr(123), feeAssetPriceModifier=0, empty signature/context, and a
+// lastBlock with BlockHeader.empty(), IndexWithinCheckpoint(4), txHashes=[TxHash.fromField(Fr(7))], empty signature).
+// Regenerate the checkpoint fixture only when the checkpoint serialization format changes on purpose.
+
+/** Legacy `BlockProposal.toBuffer()` bytes (no signedTxs, no bucket reference). */
+export const LEGACY_BLOCK_PROPOSAL_HEX =
+  '0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000000000000000000000000000000000000630000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000007000000000000000000000000000000000000000000000000000000000000000800000000';
+
+/** Legacy `CheckpointProposal.toBuffer()` bytes (lastBlock without signedTxs or bucket reference). */
+export const LEGACY_CHECKPOINT_PROPOSAL_HEX =
+  '0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000007b0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000700000000';
+
+/** Legacy `BlockProposal.getPayloadToSign()` bytes (no bucket reference). */
+export const LEGACY_BLOCK_PROPOSAL_PAYLOAD_HEX =
+  '0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000000000000000000000000000000000000630000000200000000000000000000000000000000000000000000000000000000000000070000000000000000000000000000000000000000000000000000000000000008';

package/src/parity/inbox_parity_private_inputs.ts

@@ -0,0 +1,116 @@
+import { INBOX_PARITY_SIZE_LARGE, INBOX_PARITY_SIZE_MEDIUM, INBOX_PARITY_SIZE_SMALL } from '@aztec-labs/constants';
+import { padArrayEnd } from '@aztec-labs/foundation/collection';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { bufferSchemaFor } from '@aztec-labs/foundation/schemas';
+import { BufferReader, serializeToBuffer } from '@aztec-labs/foundation/serialize';
+import { bufferToHex, hexToBuffer } from '@aztec-labs/foundation/string';
+
+/** The InboxParity size ladder, ascending. One VK per size; the prover proves the smallest that fits. */
+export const INBOX_PARITY_SIZES = [INBOX_PARITY_SIZE_SMALL, INBOX_PARITY_SIZE_MEDIUM, INBOX_PARITY_SIZE_LARGE] as const;
+
+/** A valid InboxParity ladder size. */
+export type InboxParitySize = (typeof INBOX_PARITY_SIZES)[number];
+
+/**
+ * Picks the smallest ladder size that can hold `numMessages` messages.
+ * @throws if `numMessages` exceeds the largest rung.
+ */
+export function pickInboxParitySize(numMessages: number): InboxParitySize {
+  const size = INBOX_PARITY_SIZES.find(s => numMessages <= s);
+  if (size === undefined) {
+    throw new Error(
+      `Cannot fit ${numMessages} L1-to-L2 messages into any InboxParity size (max ${INBOX_PARITY_SIZE_LARGE})`,
+    );
+  }
+  return size;
+}
+
+/**
+ * Private inputs for one `InboxParity<S>` proof (S = `size`). The prover produces exactly one per checkpoint, sized
+ * by the checkpoint's message count via {@link pickInboxParitySize}.
+ */
+export class InboxParityPrivateInputs {
+  constructor(
+    /** Ladder size S: the length of `messages` and the circuit variant to prove ({@link INBOX_PARITY_SIZES}). */
+    public readonly size: InboxParitySize,
+    /** The checkpoint's L1-to-L2 messages, padded with zeros to `size`; the first `numMessages` are real. */
+    public readonly messages: Fr[],
+    /** Number of real (non-padding) messages in `messages`. */
+    public readonly numMessages: number,
+    /** Inbox rolling hash before this checkpoint's messages (the previous checkpoint's end; genesis is zero). */
+    public readonly startRollingHash: Fr,
+    /** Prover identity committed to by the circuit, for sybil protection. */
+    public readonly proverId: Fr,
+  ) {
+    if (messages.length !== size) {
+      throw new Error(`InboxParity messages length (${messages.length}) must equal size (${size})`);
+    }
+  }
+
+  /**
+   * Builds the inputs from a checkpoint's real messages, sizing the circuit by the message count and padding the
+   * message array out to that size.
+   */
+  static fromMessages(messages: Fr[], startRollingHash: Fr, proverId: Fr): InboxParityPrivateInputs {
+    const size = pickInboxParitySize(messages.length);
+    // Explicit `<Fr, number>` keeps the result `Fr[]`; padding to the union-literal `size` would infer a deep tuple.
+    return new InboxParityPrivateInputs(
+      size,
+      padArrayEnd<Fr, number>(messages, Fr.ZERO, size),
+      messages.length,
+      startRollingHash,
+      proverId,
+    );
+  }
+
+  /** Serializes the inputs to a buffer. */
+  toBuffer() {
+    return serializeToBuffer(
+      new Fr(this.size),
+      this.messages,
+      new Fr(this.numMessages),
+      this.startRollingHash,
+      this.proverId,
+    );
+  }
+
+  /** Serializes the inputs to a hex string. */
+  toString() {
+    return bufferToHex(this.toBuffer());
+  }
+
+  /**
+   * Deserializes the inputs from a buffer.
+   * @param buffer - The buffer to deserialize from.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    const size = Fr.fromBuffer(reader).toNumber() as InboxParitySize;
+    // Array.from keeps the type `Fr[]`; readArray with the union-literal `size` would infer a deep tuple.
+    const messages = Array.from({ length: size }, () => Fr.fromBuffer(reader));
+    return new InboxParityPrivateInputs(
+      size,
+      messages,
+      Fr.fromBuffer(reader).toNumber(),
+      Fr.fromBuffer(reader),
+      Fr.fromBuffer(reader),
+    );
+  }
+
+  /**
+   * Deserializes the inputs from a hex string.
+   * @param str - The hex string to deserialize from.
+   */
+  static fromString(str: string) {
+    return InboxParityPrivateInputs.fromBuffer(hexToBuffer(str));
+  }
+
+  /** Returns a buffer representation for JSON serialization. */
+  toJSON() {
+    return this.toBuffer();
+  }
+
+  static get schema() {
+    return bufferSchemaFor(InboxParityPrivateInputs);
+  }
+}

package/src/parity/index.ts

@@ -0,0 +1,2 @@
+export * from './inbox_parity_private_inputs.js';
+export * from './parity_public_inputs.js';

package/src/parity/parity_public_inputs.ts

@@ -0,0 +1,87 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { bufferSchemaFor } from '@aztec-labs/foundation/schemas';
+import { BufferReader, serializeToBuffer } from '@aztec-labs/foundation/serialize';
+import { bufferToHex, hexToBuffer } from '@aztec-labs/foundation/string';
+import type { FieldsOf } from '@aztec-labs/foundation/types';
+
+import { L1ToL2MessageSponge } from '../messaging/l1_to_l2_message_sponge.js';
+
+export class ParityPublicInputs {
+  constructor(
+    /** Inbox rolling hash before absorbing this checkpoint's messages. */
+    public startRollingHash: Fr,
+    /** Inbox rolling hash after absorbing the checkpoint's real messages. */
+    public endRollingHash: Fr,
+    /** Message-bundle sponge after absorbing the same real messages into the empty per-checkpoint sponge. */
+    public endSponge: L1ToL2MessageSponge,
+    /** Prover identity committed to by the circuit, for sybil protection. */
+    public proverId: Fr,
+  ) {}
+
+  /**
+   * Serializes the inputs to a buffer.
+   * @returns The inputs serialized to a buffer.
+   */
+  toBuffer() {
+    return serializeToBuffer(this.startRollingHash, this.endRollingHash, this.endSponge, this.proverId);
+  }
+
+  /**
+   * Serializes the inputs to a hex string.
+   * @returns The inputs serialized to a hex string.
+   */
+  toString() {
+    return bufferToHex(this.toBuffer());
+  }
+
+  /** Returns a representation for JSON serialization. */
+  toJSON() {
+    return this.toBuffer();
+  }
+
+  /**
+   * Creates a new ParityPublicInputs instance from the given fields.
+   * @param fields - The fields to create the instance from.
+   * @returns The instance.
+   */
+  static from(fields: FieldsOf<ParityPublicInputs>): ParityPublicInputs {
+    return new ParityPublicInputs(...ParityPublicInputs.getFields(fields));
+  }
+
+  /**
+   * Extracts the fields from the given instance.
+   * @param fields - The instance to get the fields from.
+   * @returns The instance fields.
+   */
+  static getFields(fields: FieldsOf<ParityPublicInputs>) {
+    return [fields.startRollingHash, fields.endRollingHash, fields.endSponge, fields.proverId] as const;
+  }
+
+  /**
+   * Deserializes the inputs from a buffer.
+   * @param buffer - The buffer to deserialize from.
+   * @returns A new ParityPublicInputs instance.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new ParityPublicInputs(
+      reader.readObject(Fr),
+      reader.readObject(Fr),
+      reader.readObject(L1ToL2MessageSponge),
+      Fr.fromBuffer(reader),
+    );
+  }
+
+  /**
+   * Deserializes the inputs from a hex string.
+   * @param str - The hex string to deserialize from.
+   * @returns A new ParityPublicInputs instance.
+   */
+  static fromString(str: string) {
+    return ParityPublicInputs.fromBuffer(hexToBuffer(str));
+  }
+
+  static get schema() {
+    return bufferSchemaFor(ParityPublicInputs);
+  }
+}