@aztec/p2p 0.0.1-commit.d3ec352c → 0.0.1-commit.d58ff9d0

package/src/client/interface.ts

@@ -1,19 +1,23 @@
+import type { SlotNumber } from '@aztec/foundation/branded-types';
 import type { EthAddress, L2BlockId } from '@aztec/stdlib/block';
-import type { P2PApiFull } from '@aztec/stdlib/interfaces/server';
-import type { BlockAttestation, BlockProposal, P2PClientType } from '@aztec/stdlib/p2p';
-import type { Tx, TxHash } from '@aztec/stdlib/tx';
+import type { ITxProvider, P2PClient } from '@aztec/stdlib/interfaces/server';
+import type { BlockProposal, CheckpointAttestation, CheckpointProposal, TopicType } from '@aztec/stdlib/p2p';
+import type { BlockHeader, Tx, TxHash } from '@aztec/stdlib/tx';
 
 import type { PeerId } from '@libp2p/interface';
 import type { ENR } from '@nethermindeth/enr';
 
 import type { P2PConfig } from '../config.js';
 import type { AuthRequest, StatusMessage } from '../services/index.js';
+import type { ReqRespSubProtocol, ReqRespSubProtocolHandler } from '../services/reqresp/interface.js';
 import type {
-  ReqRespSubProtocol,
-  ReqRespSubProtocolHandler,
-  ReqRespSubProtocolValidators,
-} from '../services/reqresp/interface.js';
-import type { P2PBlockReceivedCallback } from '../services/service.js';
+  DuplicateAttestationInfo,
+  DuplicateProposalInfo,
+  OversizedProposalInfo,
+  P2PBlockReceivedCallback,
+  P2PCheckpointAttestationCallback,
+  P2PCheckpointReceivedCallback,
+} from '../services/service.js';
 
 /**
  * Enum defining the possible states of the p2p client.
@@ -42,7 +46,7 @@ export interface P2PSyncState {
 /**
  * Interface of a P2P client.
  **/
-export type P2P<T extends P2PClientType = P2PClientType.Full> = P2PApiFull<T> & {
+export type P2P = P2PClient & {
   /**
    * Broadcasts a block proposal to other peers.
    *
@@ -50,8 +54,15 @@ export type P2P<T extends P2PClientType = P2PClientType.Full> = P2PApiFull<T> &
    */
   broadcastProposal(proposal: BlockProposal): Promise<void>;
 
-  /** Broadcasts block attestations to other peers. */
-  broadcastAttestations(attestations: BlockAttestation[]): Promise<void>;
+  /**
+   * Broadcasts a checkpoint proposal (last block in a checkpoint) to other peers.
+   *
+   * @param proposal - the checkpoint proposal
+   */
+  broadcastCheckpointProposal(proposal: CheckpointProposal): Promise<void>;
+
+  /** Broadcasts checkpoint attestations to other peers. */
+  broadcastCheckpointAttestations(attestations: CheckpointAttestation[]): Promise<void>;
 
   /**
    * Registers a callback from the validator client that determines how to behave when
@@ -64,12 +75,48 @@ export type P2P<T extends P2PClientType = P2PClientType.Full> = P2PApiFull<T> &
   registerBlockProposalHandler(callback: P2PBlockReceivedCallback): void;
 
   /**
-   * Request a list of transactions from another peer by their tx hashes.
-   * @param txHashes - Hashes of the txs to query.
-   * @param pinnedPeerId - An optional peer id that will be used to request the tx from (in addition to other random peers).
-   * @returns A list of transactions or undefined if the transactions are not found.
+   * Registers a callback from the validator client that determines how to behave when
+   * foreign checkpoint proposals are received
+   *
+   * @param handler - A function taking a received checkpoint proposal and producing attestations
+   */
+  registerValidatorCheckpointProposalHandler(callback: P2PCheckpointReceivedCallback): void;
+
+  /**
+   * Registers a callback that runs for ALL nodes (not just validators) when a checkpoint proposal is received.
+   * Used to set the proposed checkpoint number on the archiver so the sequencer can build on top of it.
+   *
+   * @param handler - A function taking a received checkpoint proposal
+   */
+  registerAllNodesCheckpointProposalHandler(callback: P2PCheckpointReceivedCallback): void;
+
+  /**
+   * Registers a callback invoked when a duplicate proposal is detected (equivocation).
+   * The callback is triggered on the first duplicate (when count goes from 1 to 2).
+   *
+   * @param callback - Function called with info about the duplicate proposal
    */
-  requestTxsByHash(txHashes: TxHash[], pinnedPeerId: PeerId): Promise<Tx[]>;
+  registerDuplicateProposalCallback(callback: (info: DuplicateProposalInfo) => void): void;
+
+  /**
+   * Registers a callback invoked when an oversized block proposal (index at or beyond the consensus
+   * per-checkpoint block limit) is stored and re-broadcast as slashing evidence.
+   *
+   * @param callback - Function called with info about the oversized proposal
+   */
+  registerOversizedProposalCallback(callback: (info: OversizedProposalInfo) => void): void;
+
+  /**
+   * Registers a callback invoked when a duplicate attestation is detected (equivocation).
+   * A validator signing attestations for different proposals at the same slot.
+   * The callback is triggered on the first duplicate (when count goes from 1 to 2).
+   *
+   * @param callback - Function called with info about the duplicate attestation
+   */
+  registerDuplicateAttestationCallback(callback: (info: DuplicateAttestationInfo) => void): void;
+
+  /** Registers a callback invoked when a valid checkpoint attestation is accepted into the pool. */
+  registerCheckpointAttestationCallback(callback: P2PCheckpointAttestationCallback): void;
 
   /**
    * Verifies the 'tx' and, if valid, adds it to local tx pool and forwards it to other peers.
@@ -78,32 +125,26 @@ export type P2P<T extends P2PClientType = P2PClientType.Full> = P2PApiFull<T> &
   sendTx(tx: Tx): Promise<void>;
 
   /**
-   * Adds transactions to the pool. Does not send to peers or validate the tx.
-   * @param txs - The transactions.
-   * @returns The number of txs added to the pool. Note if the transaction already exists, it will not be added again.
-   **/
-  addTxsToPool(txs: Tx[]): Promise<number>;
-
-  /**
-   * Deletes 'txs' from the pool, given hashes.
-   * NOT used if we use sendTx as reconcileTxPool will handle this.
-   * @param txHashes - Hashes to check.
+   * Handles failed transaction execution by removing txs from the pool.
+   * @param txHashes - Hashes of the transactions that failed execution.
    **/
-  deleteTxs(txHashes: TxHash[]): Promise<void>;
+  handleFailedExecution(txHashes: TxHash[]): Promise<void>;
 
   /**
    * Returns a transaction in the transaction pool by its hash.
    * @param txHash  - Hash of tx to return.
+   * @param opts - Set `includeProof: false` to skip loading the tx proof from the DB.
    * @returns A single tx or undefined.
    */
-  getTxByHashFromPool(txHash: TxHash): Promise<Tx | undefined>;
+  getTxByHashFromPool(txHash: TxHash, opts?: { includeProof?: boolean }): Promise<Tx | undefined>;
 
   /**
    * Returns transactions in the transaction pool by hash.
    * @param txHashes  - Hashes of txs to return.
+   * @param opts - Set `includeProof: false` to skip loading tx proofs from the DB.
    * @returns An array of txs or undefined.
    */
-  getTxsByHashFromPool(txHashes: TxHash[]): Promise<(Tx | undefined)[]>;
+  getTxsByHashFromPool(txHashes: TxHash[], opts?: { includeProof?: boolean }): Promise<(Tx | undefined)[]>;
 
   /**
    * Checks if transactions exist in the pool
@@ -112,14 +153,6 @@ export type P2P<T extends P2PClientType = P2PClientType.Full> = P2PApiFull<T> &
    */
   hasTxsInPool(txHashes: TxHash[]): Promise<boolean[]>;
 
-  /**
-   * Returns transactions in the transaction pool by hash, requesting from the network if not found.
-   * @param txHashes  - Hashes of tx to return.
-   * @param pinnedPeerId - An optional peer id that will be used to request the tx from (in addition to other random peers).
-   * @returns An array of tx or undefined.
-   */
-  getTxsByHash(txHashes: TxHash[], pinnedPeerId: PeerId | undefined): Promise<(Tx | undefined)[]>;
-
   /**
    * Returns an archived transaction from the transaction pool by its hash.
    * @param txHash  - Hash of tx to return.
@@ -134,17 +167,43 @@ export type P2P<T extends P2PClientType = P2PClientType.Full> = P2PApiFull<T> &
    */
   getTxStatus(txHash: TxHash): Promise<'pending' | 'mined' | 'deleted' | undefined>;
 
-  /** Returns an iterator over pending txs on the mempool. */
-  iteratePendingTxs(): AsyncIterableIterator<Tx>;
+  /**
+   * Returns an iterator over pending txs on the mempool.
+   * Set `includeProof: false` to skip loading tx proofs from the DB.
+   */
+  iteratePendingTxs(opts?: { includeProof?: boolean }): AsyncIterableIterator<Tx>;
+
+  /**
+   * Returns an iterator over pending txs that have been in the pool long enough to be eligible for block building.
+   * Set `includeProof: false` to skip loading tx proofs from the DB.
+   */
+  iterateEligiblePendingTxs(opts?: { includeProof?: boolean }): AsyncIterableIterator<Tx>;
 
   /** Returns the number of pending txs in the mempool. */
   getPendingTxCount(): Promise<number>;
 
   /**
-   * Marks transactions as non-evictable in the pool.
-   * @param txHashes - Hashes of the transactions to mark as non-evictable.
+   * Returns whether at least `minCount` pending txs have been in the pool long enough to be eligible for block
+   * building. Early-exits once the threshold is met instead of counting every eligible tx.
+   */
+  hasEligiblePendingTxs(minCount: number): Promise<boolean>;
+
+  /**
+   * Protects existing transactions by hash for a given slot.
+   * Returns hashes of transactions that weren't found in the pool.
+   * @param txHashes - Hashes of the transactions to protect.
+   * @param blockHeader - The block header providing slot context.
+   * @returns Hashes of transactions not found in the pool.
+   */
+  protectTxs(txHashes: TxHash[], blockHeader: BlockHeader): Promise<TxHash[]>;
+
+  /**
+   * Prepares the pool for a new slot.
+   * Unprotects transactions from earlier slots and validates them before
+   * returning to pending state.
+   * @param slotNumber - The slot number to prepare for
    */
-  markTxsAsNonEvictable(txHashes: TxHash[]): Promise<void>;
+  prepareForSlot(slotNumber: SlotNumber): Promise<void>;
 
   /**
    * Starts the p2p client.
@@ -177,22 +236,27 @@ export type P2P<T extends P2PClientType = P2PClientType.Full> = P2PApiFull<T> &
   /** Identifies a p2p client. */
   isP2PClient(): true;
 
+  /** Returns the tx provider used for fetching transactions. */
+  getTxProvider(): ITxProvider;
+
   updateP2PConfig(config: Partial<P2PConfig>): Promise<void>;
 
-  /** Validates a set of txs. */
-  validate(txs: Tx[]): Promise<void>;
+  /** Validates a set of txs received in a block proposal. */
+  validateTxsReceivedInBlockProposal(txs: Tx[]): Promise<void>;
 
   /** Clears the db. */
   clear(): Promise<void>;
 
-  addReqRespSubProtocol(
-    subProtocol: ReqRespSubProtocol,
-    handler: ReqRespSubProtocolHandler,
-    validator?: ReqRespSubProtocolValidators[ReqRespSubProtocol],
-  ): Promise<void>;
+  addReqRespSubProtocol(subProtocol: ReqRespSubProtocol, handler: ReqRespSubProtocolHandler): Promise<void>;
 
   handleAuthRequestFromPeer(authRequest: AuthRequest, peerId: PeerId): Promise<StatusMessage>;
 
+  /** Checks if any block proposals exist for the given slot. */
+  hasBlockProposalsForSlot(slot: SlotNumber): Promise<boolean>;
+
   /** If node running this P2P stack is validator, passes in validator address to P2P layer */
   registerThisValidatorAddresses(address: EthAddress[]): void;
+
+  /** Returns the number of peers in the GossipSub mesh for a given topic type. */
+  getGossipMeshPeerCount(topicType: TopicType): Promise<number>;
 };