@aztec/stdlib 5.2.0-nightly.20260813 → 5.2.0-nightly.20260815

package/src/block/l2_block_stream/event_driven_l2_block_stream.ts

@@ -1,156 +1,51 @@
-import { type Logger, createLogger } from '@aztec/foundation/log';
+import { createLogger } from '@aztec/foundation/log';
 import { RunningPromise } from '@aztec/foundation/running-promise';
 
-import type { BlockData } from '../block_data.js';
-import type { L2Block } from '../l2_block.js';
 import {
   type ArchiverEmitter,
-  type BlockQuery,
-  type BlocksQuery,
   type L2BlockSource,
   type L2BlockSourceEventEmitter,
   L2BlockSourceEvents,
-  type L2BlockSourceUpdatedEvent,
-  type L2Tips,
 } from '../l2_block_source.js';
-import { type L2BlockStreamEventHandler, type L2BlockStreamLocalDataProvider, localTipsMatch } from './interfaces.js';
-import { L2BlockStream, type L2BlockStreamOptions, type L2BlockStreamSource } from './l2_block_stream.js';
-
-/** Derives the metadata-only {@link BlockData} view of a hydrated {@link L2Block}. */
-async function l2BlockToBlockData(block: L2Block): Promise<BlockData> {
-  return {
-    header: block.header,
-    archive: block.archive,
-    blockHash: await block.hash(),
-    checkpointNumber: block.checkpointNumber,
-    indexWithinCheckpoint: block.indexWithinCheckpoint,
-  };
-}
+import type { L2BlockStreamEventHandler, L2BlockStreamLocalDataProvider } from './interfaces.js';
+import { L2BlockStream, type L2BlockStreamOptions } from './l2_block_stream.js';
 
 /** Returns the event emitter of a source that exposes one, or undefined for plain (e.g. RPC-backed) sources. */
 function getEmitter(source: L2BlockSource | L2BlockSourceEventEmitter): ArchiverEmitter | undefined {
   return 'events' in source ? source.events : undefined;
 }
 
-/** Fast-path context for a single sync pass: blocks to serve by number, plus the tips to report as the source's. */
-type ActiveUpdate = { byNumber: Map<number, L2Block>; toTips: L2Tips };
-
-/**
- * Wraps a block source so a single sync pass can be served from blocks delivered by an aggregate update event,
- * avoiding round-trips to archiver storage. The fast path is only armed (via {@link activate}) for a pass that is
- * confirmed caught up to the event's pre-pass tips: in that case the event's `blocksAdded` contiguously cover the
- * pass's download range and `toTips` is the exact post-pass tip, so `getL2Tips` can report it without querying the
- * source. When the fast path is not armed, every read delegates to the source, so a stale or partial cache never
- * changes the sync outcome.
- */
-class HotBlockSourceAdapter implements L2BlockStreamSource {
-  /** Set for the duration of one fast-path pass; undefined when reads must delegate to the source. */
-  private active: ActiveUpdate | undefined;
-
-  constructor(
-    private readonly source: L2BlockStreamSource,
-    private readonly log: Logger,
-  ) {}
-
-  /** Arms the fast path for the current pass: serve these blocks and report `toTips` as the source tips. */
-  public activate(blocks: readonly L2Block[], toTips: L2Tips): void {
-    const byNumber = new Map<number, L2Block>();
-    for (const block of blocks) {
-      byNumber.set(block.number, block);
-    }
-    this.active = { byNumber, toTips };
-    this.log.trace(`Armed hot-block fast path`, { blocks: byNumber.size, toTips });
-  }
-
-  /** Disarms the fast path so subsequent reads delegate to the source again. */
-  public deactivate(): void {
-    this.active = undefined;
-  }
-
-  public getL2Tips(): Promise<L2Tips> {
-    return this.active ? Promise.resolve(this.active.toTips) : this.source.getL2Tips();
-  }
-
-  public getBlocks(query: BlocksQuery): Promise<L2Block[]> {
-    const served = this.active ? this.tryServeBlocksFromCache(query) : undefined;
-    return served ? Promise.resolve(served) : this.source.getBlocks(query);
-  }
-
-  public getBlockData(query: BlockQuery): Promise<BlockData | undefined> {
-    if (this.active && 'number' in query) {
-      const block = this.active.byNumber.get(query.number);
-      if (block) {
-        return l2BlockToBlockData(block);
-      }
-    }
-    return this.source.getBlockData(query);
-  }
-
-  /** Serves a block range from the cache only when it is fully covered by contiguous cached blocks. */
-  private tryServeBlocksFromCache(query: BlocksQuery): L2Block[] | undefined {
-    // Only the by-range form is cacheable, and only for the full (not checkpointed-only) chain: the cache may hold
-    // uncheckpointed blocks that an onlyCheckpointed query must not receive.
-    if (!this.active || !('from' in query) || query.onlyCheckpointed) {
-      return undefined;
-    }
-    const from = query.from;
-    const to = from + query.limit - 1;
-    const blocks: L2Block[] = [];
-    for (let n = from; n <= to; n++) {
-      const block = this.active.byNumber.get(n);
-      if (!block) {
-        // A gap inside the requested range: bail out and let the source serve the whole range.
-        return undefined;
-      }
-      blocks.push(block);
-    }
-    return blocks;
-  }
-}
-
 /**
  * Event-driven wrapper around {@link L2BlockStream}. Subscribes to the source's aggregate `l2BlockSourceUpdated`
- * event (when the source exposes one) to trigger an immediate reconciliation, while keeping the periodic poll as
- * the correctness fallback. Subsystems keep consuming the same {@link L2BlockStreamEvent}s; the archiver aggregate
- * event is handled entirely here.
- *
- * The event is passed through to the sync pass via {@link RunningPromise.trigger}. If, at the time the pass runs,
- * the stream's local tips match the event's `fromTips` (it is caught up to where the event began), the event's
- * hydrated blocks are served back through a hot-block cache and the event's `toTips` is reported as the source tips
- * — so the triggered sync re-reads neither block bodies nor tips from the archiver. Otherwise the pass delegates
- * entirely to the source, and the periodic poll guarantees eventual catch-up.
+ * event (when the source exposes one) and uses it purely as a doorbell: each event triggers an immediate
+ * reconciliation pass instead of waiting for the next tick, while the periodic poll remains the correctness
+ * fallback. Every pass reads tips and blocks authoritatively from the source, so a missed, stale, or duplicated
+ * event only affects latency. Subsystems keep consuming the same {@link L2BlockStreamEvent}s; the archiver
+ * aggregate event is handled entirely here.
  */
 export class EventDrivenL2BlockStream {
-  private readonly adapter: HotBlockSourceAdapter;
   private readonly blockStream: L2BlockStream;
-  private readonly runningPromise: RunningPromise<L2BlockSourceUpdatedEvent>;
+  private readonly runningPromise: RunningPromise;
   private readonly emitter: ArchiverEmitter | undefined;
   private started = false;
 
-  private readonly onSourceUpdated = (event: L2BlockSourceUpdatedEvent) => {
+  private readonly onSourceUpdated = () => {
     // Fire-and-forget: trigger coalesces with any in-flight or periodic pass (see RunningPromise.trigger), so a
     // burst of events does not run passes concurrently. Errors are swallowed by the inner stream's own handler.
-    void this.runningPromise
-      .trigger(event)
-      .catch(err => this.log.error(`Error in event-triggered block stream sync`, err));
+    void this.runningPromise.trigger().catch(err => this.log.error(`Error in event-triggered block stream sync`, err));
   };
 
   constructor(
     source: L2BlockSource | L2BlockSourceEventEmitter,
-    private readonly localData: L2BlockStreamLocalDataProvider,
+    localData: L2BlockStreamLocalDataProvider,
     handler: L2BlockStreamEventHandler,
     private readonly log = createLogger('types:event_driven_block_stream'),
     opts: L2BlockStreamOptions = {},
   ) {
-    this.adapter = new HotBlockSourceAdapter(source, log);
     // The inner stream's own RunningPromise is never started; this wrapper owns the polling loop and drives the
     // stream through `sync()` (which runs `work()` directly when the inner loop is stopped).
-    this.blockStream = new L2BlockStream(this.adapter, localData, handler, log, opts);
-    this.runningPromise = new RunningPromise<L2BlockSourceUpdatedEvent>(
-      this.runPass.bind(this),
-      log,
-      opts.pollIntervalMS ?? 1000,
-    );
+    this.blockStream = new L2BlockStream(source, localData, handler, log, opts);
+    this.runningPromise = new RunningPromise(() => this.blockStream.sync(), log, opts.pollIntervalMS ?? 1000);
     this.emitter = getEmitter(source);
   }
 
@@ -176,32 +71,11 @@ export class EventDrivenL2BlockStream {
   }
 
   /**
-   * Runs a synchronization pass now, bypassing the poll interval, and resolves once that pass completes. Concurrent
-   * callers and periodic ticks coalesce onto a single pass; a caller that coalesces onto an already in-flight pass
-   * can resolve against a pass that began just before it, so this guarantees freshness only up to that coalescing
-   * window. The periodic poll and per-pass reorg handling make the gap a latency effect, never a correctness one.
+   * Runs a synchronization pass now, bypassing the poll interval. Resolves once a pass that started after this call
+   * completes, so the caller observes state at least as fresh as the moment it asked. Concurrent callers coalesce
+   * onto a single such pass. Rejects if the stream is stopped before that pass runs.
    */
   public sync(): Promise<void> {
     return this.runningPromise.trigger();
   }
-
-  /**
-   * Runs a single pass over the underlying block stream. When triggered by an aggregate event and the stream is
-   * caught up to the event's pre-pass tips, the event's blocks and tips serve the pass directly; the fast path is
-   * always disarmed afterwards so a subsequent poll-driven pass reads from the source.
-   */
-  private async runPass(event?: L2BlockSourceUpdatedEvent): Promise<void> {
-    if (event) {
-      const localTips = await this.localData.getL2Tips();
-      if (localTipsMatch(localTips, event.fromTips)) {
-        this.adapter.activate(event.blocksAdded, event.toTips);
-      }
-    }
-
-    try {
-      await this.blockStream.sync();
-    } finally {
-      this.adapter.deactivate();
-    }
-  }
 }

package/src/checkpoint/simulation_overrides.ts

@@ -45,7 +45,7 @@ type CheckpointSimulationOverridesPlanInput = {
 /**
  * Builds the SimulationOverridesPlan describing the simulated L1 rollup state for a checkpoint's
  * enqueue-time simulations: `canProposeAt` (in Sequencer.doWork) and the propose-related sims
- * (validateBlockHeader, simulateProposeTx). The plan reflects "as if our pipelined parent
+ * (validateCheckpointHeader, simulateProposeTx). The plan reflects "as if our pipelined parent
  * checkpoint has landed and any required invalidation has executed" — the gap that needs to be
  * bridged at enqueue time.
  *
@@ -81,7 +81,7 @@ export async function buildCheckpointSimulationOverridesPlan(
     // `getEffectivePendingCheckpointNumber` silently collapses pending back to proven — producing
     // a spurious `Rollup__InvalidArchive` against the on-chain genesis archive. The other fields
     // (headerHash, outHash, payloadDigest) are not strictly load-bearing for `canProposeAt` /
-    // `validateBlockHeader`, but mirroring the full cell keeps the simulation byte-faithful with
+    // `validateCheckpointHeader`, but mirroring the full cell keeps the simulation byte-faithful with
     // what the actual `propose()` send will observe, which is a defense against future reads
     // taking dependencies on them.
     builder.withPendingTempCheckpointLogFields({

package/src/checkpoint/validate.ts

@@ -38,9 +38,18 @@ export function validateCheckpoint(
      * accepted by L1.
      */
     maxBlocksPerCheckpoint?: number;
+    /**
+     * Whether to tolerate a zero-tx block after the first one. Defaults to false; the L1-sync ingest path
+     * passes true for the same reason it raises `maxBlocksPerCheckpoint` — such a checkpoint is already on
+     * L1, and refusing to ingest it would stall sync rather than undo it.
+     */
+    allowEmptyNonFirstBlocks?: boolean;
   },
 ): void {
-  validateCheckpointStructure(checkpoint, { maxBlocksPerCheckpoint: opts.maxBlocksPerCheckpoint });
+  validateCheckpointStructure(checkpoint, {
+    maxBlocksPerCheckpoint: opts.maxBlocksPerCheckpoint,
+    allowEmptyNonFirstBlocks: opts.allowEmptyNonFirstBlocks,
+  });
   validateCheckpointLimits(checkpoint, opts);
   validateCheckpointBlocksLimits(checkpoint, opts);
 }
@@ -53,15 +62,16 @@ export function validateCheckpoint(
  * - Checkpoint lastArchiveRoot matches the first block's lastArchive root
  * - Sequential block numbers without gaps
  * - Sequential indexWithinCheckpoint starting at 0
+ * - Every block after the first carries at least one tx, unless `allowEmptyNonFirstBlocks` is set
  * - Archive root chaining between consecutive blocks
  * - Consistent slot number across all blocks
  * - Global variables (slot, timestamp, coinbase, feeRecipient, gasFees) match checkpoint header for each block
  */
 export function validateCheckpointStructure(
   checkpoint: Checkpoint,
-  opts: { maxBlocksPerCheckpoint?: number } = {},
+  opts: { maxBlocksPerCheckpoint?: number; allowEmptyNonFirstBlocks?: boolean } = {},
 ): void {
-  const { maxBlocksPerCheckpoint = MAX_ATTESTABLE_BLOCKS_PER_CHECKPOINT } = opts;
+  const { maxBlocksPerCheckpoint = MAX_ATTESTABLE_BLOCKS_PER_CHECKPOINT, allowEmptyNonFirstBlocks = false } = opts;
   const { blocks, number, slot } = checkpoint;
 
   if (blocks.length === 0) {
@@ -114,6 +124,18 @@ export function validateCheckpointStructure(
     }
 
     if (i > 0) {
+      // The only block-root circuit that proves a zero-tx block is `rollup_block_root_first_empty_tx`, which is
+      // pinned to index 0 of a checkpoint: it starts a fresh sponge blob and carries a non-zero in_hash, both of
+      // which the block-merge continuity checks forbid at any later index. An empty block past the first would
+      // therefore have no circuit able to prove it.
+      if (!allowEmptyNonFirstBlocks && block.body.txEffects.length === 0) {
+        throw new CheckpointValidationError(
+          `Block ${block.number} at index ${i} has no txs; only the first block of a checkpoint may be empty`,
+          number,
+          slot,
+        );
+      }
+
       const prev = blocks[i - 1];
       if (block.number !== prev.number + 1) {
         throw new CheckpointValidationError(

package/src/config/network-consensus-config.ts

@@ -1,6 +1,7 @@
 import { type L1ContractsConfig, l1ContractsConfigMappings, validateSlotDurations } from '@aztec/ethereum/config';
 import { type EnvVar, pickConfigMappings } from '@aztec/foundation/config';
 
+import { MAX_ATTESTABLE_BLOCKS_PER_CHECKPOINT } from '../deserialization/index.js';
 import type { SequencerConfig } from '../interfaces/configs.js';
 import {
   DEFAULT_CHECKPOINT_PROPOSAL_INIT_TIME,
@@ -168,6 +169,13 @@ export function validateNetworkConsensusConfig(config: NetworkConsensusConfig):
   if (config.maxBlocksPerCheckpoint < 1) {
     errors.push(`maxBlocksPerCheckpoint must be at least 1 (got ${config.maxBlocksPerCheckpoint})`);
   }
+  if (config.maxBlocksPerCheckpoint > MAX_ATTESTABLE_BLOCKS_PER_CHECKPOINT) {
+    errors.push(
+      `maxBlocksPerCheckpoint (${config.maxBlocksPerCheckpoint}) exceeds the ` +
+        `${MAX_ATTESTABLE_BLOCKS_PER_CHECKPOINT} blocks nodes will build or attest to, so the network would ` +
+        `reject block indices its own configuration admits`,
+    );
+  }
   if (config.checkpointProposalSyncGraceSeconds < 0) {
     errors.push(
       `checkpointProposalSyncGraceSeconds must be non-negative (got ${config.checkpointProposalSyncGraceSeconds})`,

package/src/config/node-rpc-config.ts

@@ -1,5 +1,5 @@
 import { DEFAULT_MAX_DEBUG_LOG_MEMORY_READS } from '@aztec/constants';
-import { type ConfigMappingsType, numberConfigHelper } from '@aztec/foundation/config';
+import { type ConfigMappingsType, booleanConfigHelper, numberConfigHelper } from '@aztec/foundation/config';
 
 export const nodeRpcConfigMappings: ConfigMappingsType<NodeRPCConfig> = {
   rpcSimulatePublicMaxGasLimit: {
@@ -23,6 +23,21 @@ export const nodeRpcConfigMappings: ConfigMappingsType<NodeRPCConfig> = {
     description: 'Maximum allowed batch size for JSON RPC batch requests.',
     defaultValue: '1mb',
   },
+  rpcCorsAllowedOrigins: {
+    env: 'RPC_CORS_ALLOWED_ORIGINS',
+    description: 'Origins allowed to make credentialed cross-origin JSON RPC requests, separated by commas.',
+    parseEnv: (value: string) =>
+      value
+        .split(',')
+        .map(origin => origin.trim())
+        .filter(Boolean),
+    defaultValue: [],
+  },
+  rpcCorsAllowAnyOrigin: {
+    env: 'RPC_CORS_ALLOW_ANY_ORIGIN',
+    description: 'Allow credentialed cross-origin JSON RPC requests from any origin.',
+    ...booleanConfigHelper(false),
+  },
 };
 
 export type NodeRPCConfig = {
@@ -34,4 +49,15 @@ export type NodeRPCConfig = {
   rpcMaxBatchSize: number;
   /** The maximum body size the RPC server will accept */
   rpcMaxBodySize: string;
+  /** Origins allowed to make credentialed cross-origin requests to the RPC server. */
+  rpcCorsAllowedOrigins?: string[];
+  /** Whether to allow credentialed cross-origin requests from any origin. */
+  rpcCorsAllowAnyOrigin?: boolean;
 };
+
+/** Resolves the CORS origin policy for an RPC server. */
+export function getRpcCorsAllowedOrigins(
+  config: Pick<NodeRPCConfig, 'rpcCorsAllowedOrigins' | 'rpcCorsAllowAnyOrigin'>,
+): string[] {
+  return config.rpcCorsAllowAnyOrigin ? ['*'] : (config.rpcCorsAllowedOrigins ?? []);
+}

package/src/interfaces/aztec-node.ts

@@ -15,7 +15,12 @@ import {
 } from '@aztec/foundation/branded-types';
 import type { Fr } from '@aztec/foundation/curves/bn254';
 import type { EthAddress } from '@aztec/foundation/eth-address';
-import { createSafeJsonRpcClient, makeFetch } from '@aztec/foundation/json-rpc/client';
+import {
+  type JsonRpcFetch,
+  type JsonRpcFetchConfig,
+  createSafeJsonRpcClient,
+  makeFetch,
+} from '@aztec/foundation/json-rpc/client';
 import { MembershipWitness, SiblingPath } from '@aztec/foundation/trees';
 
 import { z } from 'zod';
@@ -793,13 +798,18 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
 export function createAztecNodeClient(
   url: string,
   versions: Partial<ComponentsVersions> = {},
-  fetch = makeFetch([1, 2, 3], false),
+  fetch?: JsonRpcFetch,
   batchWindowMS = 0,
+  maxBatchSize?: number,
+  fetchOptions: JsonRpcFetchConfig = {},
 ): AztecNode {
+  const rpcFetch = fetch ?? makeFetch([1, 2, 3], false, undefined, fetchOptions);
+
   return createSafeJsonRpcClient<AztecNode>(url, AztecNodeApiSchema, {
     namespaceMethods: 'aztec',
-    fetch,
+    fetch: rpcFetch,
     batchWindowMS,
+    maxBatchSize,
     onResponse: getVersioningResponseHandler(versions),
   });
 }

package/src/interfaces/configs.ts

@@ -133,6 +133,11 @@ export interface SequencerConfig {
   skipBroadcastCheckpointProposal?: boolean;
   /** List of slots for which the sequencer will not produce a proposal (for testing only). Attestation paths are unaffected. */
   pauseProposingForSlots?: SlotNumber[];
+  /**
+   * Minimum number of connected p2p peers required to build and propose a checkpoint. Zero disables the
+   * check. Ignored when p2p is disabled by config.
+   */
+  minPeersToPropose?: number;
 }
 
 export const SequencerConfigSchema = zodFor<SequencerConfig>()(
@@ -186,6 +191,7 @@ export const SequencerConfigSchema = zodFor<SequencerConfig>()(
     skipBroadcastProposals: z.boolean().optional(),
     skipBroadcastCheckpointProposal: z.boolean().optional(),
     pauseProposingForSlots: z.array(SlotNumberSchema).optional(),
+    minPeersToPropose: z.number().nonnegative().optional(),
   }),
 );
 

package/src/interfaces/p2p.ts

@@ -29,6 +29,19 @@ export const PeerInfoSchema = z.discriminatedUnion('status', [
   }),
 ]);
 
+/** Connectivity of the p2p stack: whether it is enabled at all, and how many peers are currently connected. */
+export type P2PConnectivity = {
+  /** False when the node runs without a p2p stack (eg sandbox or single-node setups). */
+  enabled: boolean;
+  /** Number of peers currently connected. Always zero when p2p is disabled. */
+  connectedPeers: number;
+};
+
+export const P2PConnectivitySchema = z.object({
+  enabled: z.boolean(),
+  connectedPeers: z.number(),
+});
+
 /** Exposed API to the P2P module. */
 export interface P2PApi {
   /**
@@ -54,6 +67,13 @@ export interface P2PApi {
    */
   getPeers(includePending?: boolean): Promise<PeerInfo[]>;
 
+  /**
+   * Returns whether the p2p stack is enabled on this node, and the number of peers it is connected to.
+   * Nodes running without p2p report `enabled: false`, so consumers can tell a disabled stack apart from a
+   * stack that is enabled but has no peers.
+   */
+  getP2PConnectivity(): Promise<P2PConnectivity>;
+
   /**
    * Queries the Attestation pool for checkpoint attestations for the given slot.
    *
@@ -116,4 +136,5 @@ export const P2PApiSchema: ApiSchemaFor<P2PApi> = {
   getPendingTxCount: z.function({ input: z.tuple([]), output: schemas.Integer }),
   getEncodedEnr: z.function({ input: z.tuple([]), output: z.string().optional() }),
   getPeers: z.function({ input: z.tuple([optional(z.boolean())]), output: z.array(PeerInfoSchema) }),
+  getP2PConnectivity: z.function({ input: z.tuple([]), output: P2PConnectivitySchema }),
 };

package/src/interfaces/validator.ts

@@ -11,6 +11,8 @@ import type {
   CheckpointAttestation,
   CheckpointProposal,
   CheckpointProposalOptions,
+  ValidatedBlockProposal,
+  ValidatedCheckpointProposalCore,
 } from '@aztec/stdlib/p2p';
 import type { CheckpointHeader } from '@aztec/stdlib/rollup';
 import type { BlockHeader, Tx } from '@aztec/stdlib/tx';
@@ -172,18 +174,18 @@ export interface Validator {
   ): Promise<CheckpointProposal>;
 
   /**
-   * Validate a block proposal from a peer.
+   * Validate a block proposal from a peer that has already passed p2p ingress validation.
    * Note: Validators do NOT attest to individual blocks - attestations are only for checkpoint proposals.
    * @returns true if the proposal is valid, false otherwise
    */
-  validateBlockProposal(proposal: BlockProposal, sender: PeerId): Promise<boolean>;
+  validateBlockProposal(proposal: ValidatedBlockProposal, sender: PeerId): Promise<boolean>;
 
   /**
-   * Validate and attest to a checkpoint proposal from a peer.
+   * Validate and attest to a checkpoint proposal from a peer that has already passed p2p ingress validation.
    * @returns Checkpoint attestations if valid, undefined otherwise
    */
   attestToCheckpointProposal(
-    proposal: CheckpointProposal,
+    proposal: ValidatedCheckpointProposalCore,
     sender: PeerId,
   ): Promise<CheckpointAttestation[] | undefined>;
 

package/src/p2p/index.ts

@@ -8,6 +8,7 @@ export * from './interface.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/validated_proposal.ts

@@ -0,0 +1,43 @@
+import type { Branded } from '@aztec/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;
+}