@aztec/p2p 0.60.0 → 0.62.0

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@aztec/p2p",
-  "version": "0.60.0",
+  "version": "0.62.0",
   "type": "module",
-  "exports": "./dest/index.js",
+  "exports": {
+    ".": "./dest/index.js",
+    "./mocks": "./dest/mocks/index.js",
+    "./bootstrap": "./dest/bootstrap/bootstrap.js"
+  },
   "typedocOptions": {
     "entryPoints": [
       "./src/index.ts"
@@ -59,11 +63,11 @@
     "testTimeout": 15000
   },
   "dependencies": {
-    "@aztec/circuit-types": "0.60.0",
-    "@aztec/circuits.js": "0.60.0",
-    "@aztec/foundation": "0.60.0",
-    "@aztec/kv-store": "0.60.0",
-    "@aztec/telemetry-client": "0.60.0",
+    "@aztec/circuit-types": "0.62.0",
+    "@aztec/circuits.js": "0.62.0",
+    "@aztec/foundation": "0.62.0",
+    "@aztec/kv-store": "0.62.0",
+    "@aztec/telemetry-client": "0.62.0",
     "@chainsafe/discv5": "9.0.0",
     "@chainsafe/enr": "3.0.0",
     "@chainsafe/libp2p-gossipsub": "13.0.0",
@@ -93,6 +97,7 @@
     "@jest/globals": "^29.5.0",
     "@types/jest": "^29.5.0",
     "@types/node": "^18.14.6",
+    "get-port": "^7.1.0",
     "it-drain": "^3.0.5",
     "it-length": "^3.0.6",
     "jest": "^29.5.0",

package/src/client/index.ts

@@ -16,7 +16,7 @@ import { AztecKVTxPool, type TxPool } from '../mem_pools/tx_pool/index.js';
 import { DiscV5Service } from '../service/discV5_service.js';
 import { DummyP2PService } from '../service/dummy_service.js';
 import { LibP2PService, createLibP2PPeerId } from '../service/index.js';
-import { getPublicIp, resolveAddressIfNecessary, splitAddressPort } from '../util.js';
+import { configureP2PClientAddresses } from '../util.js';
 
 export * from './p2p_client.js';
 
@@ -67,50 +67,3 @@ export const createP2PClient = async (
   }
   return new P2PClient(store, l2BlockSource, mempools, p2pService, config.keepProvenTxsInPoolFor, telemetry);
 };
-
-async function configureP2PClientAddresses(_config: P2PConfig & DataStoreConfig): Promise<P2PConfig & DataStoreConfig> {
-  const config = { ..._config };
-  const {
-    tcpAnnounceAddress: configTcpAnnounceAddress,
-    udpAnnounceAddress: configUdpAnnounceAddress,
-    queryForIp,
-  } = config;
-
-  config.tcpAnnounceAddress = configTcpAnnounceAddress
-    ? await resolveAddressIfNecessary(configTcpAnnounceAddress)
-    : undefined;
-  config.udpAnnounceAddress = configUdpAnnounceAddress
-    ? await resolveAddressIfNecessary(configUdpAnnounceAddress)
-    : undefined;
-
-  // create variable for re-use if needed
-  let publicIp;
-
-  // check if no announce IP was provided
-  const splitTcpAnnounceAddress = splitAddressPort(configTcpAnnounceAddress || '', true);
-  if (splitTcpAnnounceAddress.length == 2 && splitTcpAnnounceAddress[0] === '') {
-    if (queryForIp) {
-      publicIp = await getPublicIp();
-      const tcpAnnounceAddress = `${publicIp}:${splitTcpAnnounceAddress[1]}`;
-      config.tcpAnnounceAddress = tcpAnnounceAddress;
-    } else {
-      throw new Error(
-        `Invalid announceTcpAddress provided: ${configTcpAnnounceAddress}. Expected format: <addr>:<port>`,
-      );
-    }
-  }
-
-  const splitUdpAnnounceAddress = splitAddressPort(configUdpAnnounceAddress || '', true);
-  if (splitUdpAnnounceAddress.length == 2 && splitUdpAnnounceAddress[0] === '') {
-    // If announceUdpAddress is not provided, use announceTcpAddress
-    if (!queryForIp && config.tcpAnnounceAddress) {
-      config.udpAnnounceAddress = config.tcpAnnounceAddress;
-    } else if (queryForIp) {
-      const udpPublicIp = publicIp || (await getPublicIp());
-      const udpAnnounceAddress = `${udpPublicIp}:${splitUdpAnnounceAddress[1]}`;
-      config.udpAnnounceAddress = udpAnnounceAddress;
-    }
-  }
-
-  return config;
-}

package/src/client/p2p_client.ts

@@ -3,20 +3,22 @@ import {
   type BlockProposal,
   type EpochProofQuote,
   type L2Block,
-  L2BlockDownloader,
   type L2BlockId,
   type L2BlockSource,
+  L2BlockStream,
+  type L2BlockStreamEvent,
+  type L2Tips,
   type Tx,
   type TxHash,
 } from '@aztec/circuit-types';
 import { INITIAL_L2_BLOCK_NUM } from '@aztec/circuits.js/constants';
 import { createDebugLogger } from '@aztec/foundation/log';
-import { type AztecKVStore, type AztecSingleton } from '@aztec/kv-store';
+import { type AztecKVStore, type AztecMap, type AztecSingleton } from '@aztec/kv-store';
 import { Attributes, type TelemetryClient, WithTracer, trackSpan } from '@aztec/telemetry-client';
 
 import { type ENR } from '@chainsafe/enr';
 
-import { getP2PConfigEnvVars } from '../config.js';
+import { getP2PConfigFromEnv } from '../config.js';
 import { type AttestationPool } from '../mem_pools/attestation_pool/attestation_pool.js';
 import { type EpochProofQuotePool } from '../mem_pools/epoch_proof_quote_pool/epoch_proof_quote_pool.js';
 import { type MemPools } from '../mem_pools/interface.js';
@@ -77,11 +79,11 @@ export interface P2P {
   getEpochProofQuotes(epoch: bigint): Promise<EpochProofQuote[]>;
 
   /**
-   * Broadcasts an EpochProofQuote to other peers.
+   * Adds an EpochProofQuote to the pool and broadcasts an EpochProofQuote to other peers.
    *
    * @param quote - the quote to broadcast
    */
-  broadcastEpochProofQuote(quote: EpochProofQuote): void;
+  addEpochProofQuote(quote: EpochProofQuote): Promise<void>;
 
   /**
    * Registers a callback from the validator client that determines how to behave when
@@ -130,7 +132,14 @@ export interface P2P {
    * @param txHash  - Hash of tx to return.
    * @returns A single tx or undefined.
    */
-  getTxByHash(txHash: TxHash): Tx | undefined;
+  getTxByHashFromPool(txHash: TxHash): Tx | undefined;
+
+  /**
+   * Returns a transaction in the transaction pool by its hash, requesting it from the network if it is not found.
+   * @param txHash  - Hash of tx to return.
+   * @returns A single tx or undefined.
+   */
+  getTxByHash(txHash: TxHash): Promise<Tx | undefined>;
 
   /**
    * Returns whether the given tx hash is flagged as pending or mined.
@@ -172,12 +181,6 @@ export interface P2P {
  * The P2P client implementation.
  */
 export class P2PClient extends WithTracer implements P2P {
-  /** L2 block download to stay in sync with latest blocks. */
-  private latestBlockDownloader: L2BlockDownloader;
-
-  /** L2 block download to stay in sync with proven blocks. */
-  private provenBlockDownloader: L2BlockDownloader;
-
   /** Property that indicates whether the client is running. */
   private stopping = false;
 
@@ -190,6 +193,7 @@ export class P2PClient extends WithTracer implements P2P {
   private latestBlockNumberAtStart = -1;
   private provenBlockNumberAtStart = -1;
 
+  private synchedBlockHashes: AztecMap<number, string>;
   private synchedLatestBlockNumber: AztecSingleton<number>;
   private synchedProvenBlockNumber: AztecSingleton<number>;
 
@@ -197,6 +201,8 @@ export class P2PClient extends WithTracer implements P2P {
   private attestationPool: AttestationPool;
   private epochProofQuotePool: EpochProofQuotePool;
 
+  private blockStream;
+
   /**
    * In-memory P2P client constructor.
    * @param store - The client's instance of the KV store.
@@ -217,14 +223,14 @@ export class P2PClient extends WithTracer implements P2P {
   ) {
     super(telemetryClient, 'P2PClient');
 
-    const { blockCheckIntervalMS: checkInterval, l2QueueSize: p2pL2QueueSize } = getP2PConfigEnvVars();
-    const l2DownloaderOpts = { maxQueueSize: p2pL2QueueSize, pollIntervalMS: checkInterval };
-    // TODO(palla/prover-node): This effectively downloads blocks twice from the archiver, which is an issue
-    // if the archiver is remote. We should refactor this so the downloader keeps a single queue and handles
-    // latest/proven metadata, as well as block reorgs.
-    this.latestBlockDownloader = new L2BlockDownloader(l2BlockSource, l2DownloaderOpts);
-    this.provenBlockDownloader = new L2BlockDownloader(l2BlockSource, { ...l2DownloaderOpts, proven: true });
+    const { blockCheckIntervalMS, blockRequestBatchSize } = getP2PConfigFromEnv();
 
+    this.blockStream = new L2BlockStream(l2BlockSource, this, this, {
+      batchSize: blockRequestBatchSize,
+      pollIntervalMS: blockCheckIntervalMS,
+    });
+
+    this.synchedBlockHashes = store.openMap('p2p_pool_block_hashes');
     this.synchedLatestBlockNumber = store.openSingleton('p2p_pool_last_l2_block');
     this.synchedProvenBlockNumber = store.openSingleton('p2p_pool_last_proven_l2_block');
 
@@ -233,19 +239,88 @@ export class P2PClient extends WithTracer implements P2P {
     this.epochProofQuotePool = mempools.epochProofQuotePool;
   }
 
+  public getL2BlockHash(number: number): Promise<string | undefined> {
+    return Promise.resolve(this.synchedBlockHashes.get(number));
+  }
+
+  public getL2Tips(): Promise<L2Tips> {
+    const latestBlockNumber = this.getSyncedLatestBlockNum();
+    let latestBlockHash: string | undefined;
+    const provenBlockNumber = this.getSyncedProvenBlockNum();
+    let provenBlockHash: string | undefined;
+
+    if (latestBlockNumber > 0) {
+      latestBlockHash = this.synchedBlockHashes.get(latestBlockNumber);
+      if (typeof latestBlockHash === 'undefined') {
+        this.log.warn(`Block hash for latest block ${latestBlockNumber} not found`);
+        throw new Error();
+      }
+    }
+
+    if (provenBlockNumber > 0) {
+      provenBlockHash = this.synchedBlockHashes.get(provenBlockNumber);
+      if (typeof provenBlockHash === 'undefined') {
+        this.log.warn(`Block hash for proven block ${provenBlockNumber} not found`);
+        throw new Error();
+      }
+    }
+
+    return Promise.resolve({
+      latest: { hash: latestBlockHash!, number: latestBlockNumber },
+      proven: { hash: provenBlockHash!, number: provenBlockNumber },
+      finalized: { hash: provenBlockHash!, number: provenBlockNumber },
+    });
+  }
+
+  public async handleBlockStreamEvent(event: L2BlockStreamEvent): Promise<void> {
+    this.log.debug(`Handling block stream event ${event.type}`);
+    switch (event.type) {
+      case 'blocks-added':
+        await this.handleLatestL2Blocks(event.blocks);
+        break;
+      case 'chain-finalized':
+        // TODO (alexg): I think we can prune the block hashes map here
+        break;
+      case 'chain-proven': {
+        const from = this.getSyncedProvenBlockNum() + 1;
+        const limit = event.blockNumber - from + 1;
+        await this.handleProvenL2Blocks(await this.l2BlockSource.getBlocks(from, limit));
+        break;
+      }
+      case 'chain-pruned':
+        await this.handlePruneL2Blocks(event.blockNumber);
+        break;
+      default: {
+        const _: never = event;
+        break;
+      }
+    }
+  }
+
   #assertIsReady() {
+    // this.log.info('Checking if p2p client is ready, current state: ', this.currentState);
     if (!this.isReady()) {
       throw new Error('P2P client not ready');
     }
   }
 
+  /**
+   * Adds an EpochProofQuote to the pool and broadcasts an EpochProofQuote to other peers.
+   * @param quote - the quote to broadcast
+   */
+  addEpochProofQuote(quote: EpochProofQuote): Promise<void> {
+    this.epochProofQuotePool.addQuote(quote);
+    this.broadcastEpochProofQuote(quote);
+    return Promise.resolve();
+  }
+
   getEpochProofQuotes(epoch: bigint): Promise<EpochProofQuote[]> {
     return Promise.resolve(this.epochProofQuotePool.getQuotes(epoch));
   }
 
   broadcastEpochProofQuote(quote: EpochProofQuote): void {
     this.#assertIsReady();
-    this.epochProofQuotePool.addQuote(quote);
+    this.log.info('Broadcasting epoch proof quote', quote.toViemArgs());
     return this.p2pService.propagate(quote);
   }
 
@@ -286,21 +361,7 @@ export class P2PClient extends WithTracer implements P2P {
     // publish any txs in TxPool after its doing initial sync
     this.syncPromise = this.syncPromise.then(() => this.publishStoredTxs());
 
-    // start looking for further blocks
-    const processLatest = async () => {
-      while (!this.stopping) {
-        await this.latestBlockDownloader.getBlocks(1).then(this.handleLatestL2Blocks.bind(this));
-      }
-    };
-    const processProven = async () => {
-      while (!this.stopping) {
-        await this.provenBlockDownloader.getBlocks(1).then(this.handleProvenL2Blocks.bind(this));
-      }
-    };
-
-    this.runningPromise = Promise.all([processLatest(), processProven()]).then(() => {});
-    this.latestBlockDownloader.start(syncedLatestBlock);
-    this.provenBlockDownloader.start(syncedLatestBlock);
+    this.blockStream.start();
     this.log.verbose(`Started block downloader from block ${syncedLatestBlock}`);
 
     return this.syncPromise;
@@ -315,8 +376,7 @@ export class P2PClient extends WithTracer implements P2P {
     this.stopping = true;
     await this.p2pService.stop();
     this.log.debug('Stopped p2p service');
-    await this.latestBlockDownloader.stop();
-    await this.provenBlockDownloader.stop();
+    await this.blockStream.stop();
     this.log.debug('Stopped block downloader');
     await this.runningPromise;
     this.setCurrentState(P2PClientState.STOPPED);
@@ -388,7 +448,7 @@ export class P2PClient extends WithTracer implements P2P {
     } else if (filter === 'mined') {
       return this.txPool
         .getMinedTxHashes()
-        .map(txHash => this.txPool.getTxByHash(txHash))
+        .map(([txHash]) => this.txPool.getTxByHash(txHash))
         .filter((tx): tx is Tx => !!tx);
     } else if (filter === 'pending') {
       return this.txPool
@@ -406,10 +466,24 @@ export class P2PClient extends WithTracer implements P2P {
    * @param txHash - Hash of the transaction to look for in the pool.
    * @returns A single tx or undefined.
    */
-  getTxByHash(txHash: TxHash): Tx | undefined {
+  getTxByHashFromPool(txHash: TxHash): Tx | undefined {
     return this.txPool.getTxByHash(txHash);
   }
 
+  /**
+   * Returns a transaction in the transaction pool by its hash.
+   * If the transaction is not in the pool, it will be requested from the network.
+   * @param txHash - Hash of the transaction to look for in the pool.
+   * @returns A single tx or undefined.
+   */
+  getTxByHash(txHash: TxHash): Promise<Tx | undefined> {
+    const tx = this.txPool.getTxByHash(txHash);
+    if (tx) {
+      return Promise.resolve(tx);
+    }
+    return this.requestTxByHash(txHash);
+  }
+
   /**
    * Verifies the 'tx' and, if valid, adds it to local tx pool and forwards it to other peers.
    * @param tx - The tx to verify.
@@ -493,7 +567,7 @@ export class P2PClient extends WithTracer implements P2P {
   private async markTxsAsMinedFromBlocks(blocks: L2Block[]): Promise<void> {
     for (const block of blocks) {
       const txHashes = block.body.txEffects.map(txEffect => txEffect.txHash);
-      await this.txPool.markAsMined(txHashes);
+      await this.txPool.markAsMined(txHashes, block.number);
     }
   }
 
@@ -519,8 +593,10 @@ export class P2PClient extends WithTracer implements P2P {
     if (!blocks.length) {
       return Promise.resolve();
     }
+
     await this.markTxsAsMinedFromBlocks(blocks);
     const lastBlockNum = blocks[blocks.length - 1].number;
+    await Promise.all(blocks.map(block => this.synchedBlockHashes.set(block.number, block.hash().toString())));
     await this.synchedLatestBlockNumber.set(lastBlockNum);
     this.log.debug(`Synched to latest block ${lastBlockNum}`);
     await this.startServiceIfSynched();
@@ -558,6 +634,46 @@ export class P2PClient extends WithTracer implements P2P {
     await this.startServiceIfSynched();
   }
 
+  /**
+   * Updates the tx pool after a chain prune.
+   * @param latestBlock - The block number the chain was pruned to.
+   */
+  private async handlePruneL2Blocks(latestBlock: number): Promise<void> {
+    const txsToDelete: TxHash[] = [];
+    for (const tx of this.txPool.getAllTxs()) {
+      // every tx that's been generated against a block that has now been pruned is no longer valid
+      if (tx.data.constants.historicalHeader.globalVariables.blockNumber.toNumber() > latestBlock) {
+        txsToDelete.push(tx.getTxHash());
+      }
+    }
+
+    this.log.info(
+      `Detected chain prune. Removing invalid txs count=${
+        txsToDelete.length
+      } newLatestBlock=${latestBlock} previousLatestBlock=${this.getSyncedLatestBlockNum()}`,
+    );
+
+    // delete invalid txs (both pending and mined)
+    await this.txPool.deleteTxs(txsToDelete);
+
+    // everything left in the mined set was built against a block on the proven chain so its still valid
+    // move back to pending the txs that were reorged out of the chain
+    // NOTE: we can't move _all_ txs back to pending because the tx pool could keep hold of mined txs for longer
+    // (see this.keepProvenTxsFor)
+    const txsToMoveToPending: TxHash[] = [];
+    for (const [txHash, blockNumber] of this.txPool.getMinedTxHashes()) {
+      if (blockNumber > latestBlock) {
+        txsToMoveToPending.push(txHash);
+      }
+    }
+
+    this.log.info(`Moving ${txsToMoveToPending.length} mined txs back to pending`);
+    await this.txPool.markMinedAsPending(txsToMoveToPending);
+
+    await this.synchedLatestBlockNumber.set(latestBlock);
+    // no need to update block hashes, as they will be updated as new blocks are added
+  }
+
   private async startServiceIfSynched() {
     if (
       this.currentState === P2PClientState.SYNCHING &&

package/src/config.ts

@@ -23,6 +23,11 @@ export interface P2PConfig extends P2PReqRespConfig {
    */
   blockCheckIntervalMS: number;
 
+  /**
+   * The number of blocks to fetch in a single batch.
+   */
+  blockRequestBatchSize: number;
+
   /**
    * The frequency in which to check for new peers.
    */
@@ -295,6 +300,11 @@ export const p2pConfigMappings: ConfigMappingsType<P2PConfig> = {
     description: 'The chain id of the L1 chain.',
     ...numberConfigHelper(31337),
   },
+  blockRequestBatchSize: {
+    env: 'P2P_BLOCK_REQUEST_BATCH_SIZE',
+    description: 'The number of blocks to fetch in a single batch.',
+    ...numberConfigHelper(20),
+  },
   ...p2pReqRespConfigMappings,
 };
 
@@ -302,7 +312,7 @@ export const p2pConfigMappings: ConfigMappingsType<P2PConfig> = {
  * Gets the config values for p2p client from environment variables.
  * @returns The config values for p2p client.
  */
-export function getP2PConfigEnvVars(): P2PConfig {
+export function getP2PConfigFromEnv(): P2PConfig {
   return getConfigFromMappings<P2PConfig>(p2pConfigMappings);
 }
 

package/src/mem_pools/tx_pool/aztec_kv_tx_pool.ts

@@ -19,7 +19,7 @@ export class AztecKVTxPool implements TxPool {
   /** Index for pending txs. */
   #pendingTxs: AztecSet<string>;
   /** Index for mined txs. */
-  #minedTxs: AztecSet<string>;
+  #minedTxs: AztecMap<string, number>;
 
   #log: Logger;
 
@@ -32,7 +32,7 @@ export class AztecKVTxPool implements TxPool {
    */
   constructor(store: AztecKVStore, telemetry: TelemetryClient, log = createDebugLogger('aztec:tx_pool')) {
     this.#txs = store.openMap('txs');
-    this.#minedTxs = store.openSet('minedTxs');
+    this.#minedTxs = store.openMap('minedTxs');
     this.#pendingTxs = store.openSet('pendingTxs');
 
     this.#store = store;
@@ -40,12 +40,12 @@ export class AztecKVTxPool implements TxPool {
     this.#metrics = new PoolInstrumentation(telemetry, 'AztecKVTxPool');
   }
 
-  public markAsMined(txHashes: TxHash[]): Promise<void> {
+  public markAsMined(txHashes: TxHash[], blockNumber: number): Promise<void> {
     return this.#store.transaction(() => {
       let deleted = 0;
       for (const hash of txHashes) {
         const key = hash.toString();
-        void this.#minedTxs.add(key);
+        void this.#minedTxs.set(key, blockNumber);
         if (this.#pendingTxs.has(key)) {
           deleted++;
           void this.#pendingTxs.delete(key);
@@ -56,12 +56,41 @@ export class AztecKVTxPool implements TxPool {
     });
   }
 
+  public markMinedAsPending(txHashes: TxHash[]): Promise<void> {
+    if (txHashes.length === 0) {
+      return Promise.resolve();
+    }
+
+    return this.#store.transaction(() => {
+      let deleted = 0;
+      let added = 0;
+      for (const hash of txHashes) {
+        const key = hash.toString();
+        if (this.#minedTxs.has(key)) {
+          deleted++;
+          void this.#minedTxs.delete(key);
+        }
+
+        if (this.#txs.has(key)) {
+          added++;
+          void this.#pendingTxs.add(key);
+        }
+      }
+
+      this.#metrics.recordRemovedObjects(deleted, 'mined');
+      this.#metrics.recordAddedObjects(added, 'pending');
+    });
+  }
+
   public getPendingTxHashes(): TxHash[] {
     return Array.from(this.#pendingTxs.entries()).map(x => TxHash.fromString(x));
   }
 
-  public getMinedTxHashes(): TxHash[] {
-    return Array.from(this.#minedTxs.entries()).map(x => TxHash.fromString(x));
+  public getMinedTxHashes(): [TxHash, number][] {
+    return Array.from(this.#minedTxs.entries()).map(([txHash, blockNumber]) => [
+      TxHash.fromString(txHash),
+      blockNumber,
+    ]);
   }
 
   public getTxStatus(txHash: TxHash): 'pending' | 'mined' | undefined {

package/src/mem_pools/tx_pool/memory_tx_pool.ts

@@ -14,7 +14,7 @@ export class InMemoryTxPool implements TxPool {
    * Our tx pool, stored as a Map in-memory, with K: tx hash and V: the transaction.
    */
   private txs: Map<bigint, Tx>;
-  private minedTxs: Set<bigint>;
+  private minedTxs: Map<bigint, number>;
   private pendingTxs: Set<bigint>;
 
   private metrics: PoolInstrumentation<Tx>;
@@ -25,15 +25,15 @@ export class InMemoryTxPool implements TxPool {
    */
   constructor(telemetry: TelemetryClient, private log = createDebugLogger('aztec:tx_pool')) {
     this.txs = new Map<bigint, Tx>();
-    this.minedTxs = new Set();
+    this.minedTxs = new Map();
     this.pendingTxs = new Set();
     this.metrics = new PoolInstrumentation(telemetry, 'InMemoryTxPool');
   }
 
-  public markAsMined(txHashes: TxHash[]): Promise<void> {
+  public markAsMined(txHashes: TxHash[], blockNumber: number): Promise<void> {
     const keys = txHashes.map(x => x.toBigInt());
     for (const key of keys) {
-      this.minedTxs.add(key);
+      this.minedTxs.set(key, blockNumber);
       this.pendingTxs.delete(key);
     }
     this.metrics.recordRemovedObjects(txHashes.length, 'pending');
@@ -41,12 +41,38 @@ export class InMemoryTxPool implements TxPool {
     return Promise.resolve();
   }
 
+  public markMinedAsPending(txHashes: TxHash[]): Promise<void> {
+    if (txHashes.length === 0) {
+      return Promise.resolve();
+    }
+
+    const keys = txHashes.map(x => x.toBigInt());
+    let deleted = 0;
+    let added = 0;
+    for (const key of keys) {
+      if (this.minedTxs.delete(key)) {
+        deleted++;
+      }
+
+      // only add back to the pending set if we have the tx object
+      if (this.txs.has(key)) {
+        added++;
+        this.pendingTxs.add(key);
+      }
+    }
+
+    this.metrics.recordRemovedObjects(deleted, 'mined');
+    this.metrics.recordAddedObjects(added, 'pending');
+
+    return Promise.resolve();
+  }
+
   public getPendingTxHashes(): TxHash[] {
     return Array.from(this.pendingTxs).map(x => TxHash.fromBigInt(x));
   }
 
-  public getMinedTxHashes(): TxHash[] {
-    return Array.from(this.minedTxs).map(x => TxHash.fromBigInt(x));
+  public getMinedTxHashes(): [TxHash, number][] {
+    return Array.from(this.minedTxs.entries()).map(([txHash, blockNumber]) => [TxHash.fromBigInt(txHash), blockNumber]);
   }
 
   public getTxStatus(txHash: TxHash): 'pending' | 'mined' | undefined {

package/src/mem_pools/tx_pool/tx_pool.ts

@@ -21,7 +21,14 @@ export interface TxPool {
    * Marks the set of txs as mined, as opposed to pending.
    * @param txHashes - Hashes of the txs to flag as mined.
    */
-  markAsMined(txHashes: TxHash[]): Promise<void>;
+  markAsMined(txHashes: TxHash[], blockNumber: number): Promise<void>;
+
+  /**
+   * Moves mined txs back to the pending set in the case of a reorg.
+   * Note: txs not known by this peer will be ignored.
+   * @param txHashes - Hashes of the txs to flag as pending.
+   */
+  markMinedAsPending(txHashes: TxHash[]): Promise<void>;
 
   /**
    * Deletes transactions from the pool. Tx hashes that are not present are ignored.
@@ -51,7 +58,7 @@ export interface TxPool {
    * Gets the hashes of mined transactions currently in the tx pool.
    * @returns An array of mined transaction hashes found in the tx pool.
    */
-  getMinedTxHashes(): TxHash[];
+  getMinedTxHashes(): [tx: TxHash, blockNumber: number][];
 
   /**
    * Returns whether the given tx hash is flagged as pending or mined.

package/src/mem_pools/tx_pool/tx_pool_test_suite.ts

@@ -38,14 +38,46 @@ export function describeTxPool(getTxPool: () => TxPool) {
     const tx2 = mockTx(2);
 
     await pool.addTxs([tx1, tx2]);
-    await pool.markAsMined([tx1.getTxHash()]);
+    await pool.markAsMined([tx1.getTxHash()], 1);
 
     expect(pool.getTxByHash(tx1.getTxHash())).toEqual(tx1);
     expect(pool.getTxStatus(tx1.getTxHash())).toEqual('mined');
-    expect(pool.getMinedTxHashes()).toEqual([tx1.getTxHash()]);
+    expect(pool.getMinedTxHashes()).toEqual([[tx1.getTxHash(), 1]]);
     expect(pool.getPendingTxHashes()).toEqual([tx2.getTxHash()]);
   });
 
+  it('Marks txs as pending after being mined', async () => {
+    const tx1 = mockTx(1);
+    const tx2 = mockTx(2);
+
+    await pool.addTxs([tx1, tx2]);
+    await pool.markAsMined([tx1.getTxHash()], 1);
+
+    await pool.markMinedAsPending([tx1.getTxHash()]);
+    expect(pool.getMinedTxHashes()).toEqual([]);
+    const pending = pool.getPendingTxHashes();
+    expect(pending).toHaveLength(2);
+    expect(pending).toEqual(expect.arrayContaining([tx1.getTxHash(), tx2.getTxHash()]));
+  });
+
+  it('Only marks txs as pending if they are known', async () => {
+    const tx1 = mockTx(1);
+    // simulate a situation where not all peers have all the txs
+    const someTxHashThatThisPeerDidNotSee = mockTx(2).getTxHash();
+    await pool.addTxs([tx1]);
+    // this peer knows that tx2 was mined, but it does not have the tx object
+    await pool.markAsMined([tx1.getTxHash(), someTxHashThatThisPeerDidNotSee], 1);
+    expect(pool.getMinedTxHashes()).toEqual([
+      [tx1.getTxHash(), 1],
+      [someTxHashThatThisPeerDidNotSee, 1],
+    ]);
+
+    // reorg: both txs should now become available again
+    await pool.markMinedAsPending([tx1.getTxHash(), someTxHashThatThisPeerDidNotSee]);
+    expect(pool.getMinedTxHashes()).toEqual([]);
+    expect(pool.getPendingTxHashes()).toEqual([tx1.getTxHash()]); // tx2 is not in the pool
+  });
+
   it('Returns all transactions in the pool', async () => {
     const tx1 = mockTx(1);
     const tx2 = mockTx(2);