Merge branch 'v5-next' into merge-train/fairies-v5

Author: AztecBot

yarn-project/archiver/src/modules/data_source_base.ts

@@ -224,23 +224,6 @@ export abstract class ArchiverDataSourceBase
     }
   }
 
-  /**
-   * Resolves a {@link CheckpointsQuery} to a concrete `{from, limit}` pair used by BlockStore,
-   * or undefined when the epoch has no checkpoints.
-   */
-  private async resolveCheckpointsQuery(
-    query: CheckpointsQuery,
-  ): Promise<{ from: CheckpointNumber; limit: number } | undefined> {
-    if ('from' in query) {
-      return query;
-    }
-    const numbers = await this.getCheckpointNumbersForEpoch(query.epoch);
-    if (numbers.length === 0) {
-      return undefined;
-    }
-    return { from: numbers[0], limit: numbers.length };
-  }
-
   public async getCheckpoint(query: CheckpointQuery): Promise<PublishedCheckpoint | undefined> {
     const number = await this.resolveCheckpointQuery(query);
     if (number === undefined || number === 0) {
@@ -254,11 +237,7 @@ export abstract class ArchiverDataSourceBase
   }
 
   public async getCheckpoints(query: CheckpointsQuery): Promise<PublishedCheckpoint[]> {
-    const resolved = await this.resolveCheckpointsQuery(query);
-    if (!resolved) {
-      return [];
-    }
-    const checkpoints = await this.stores.blocks.getRangeOfCheckpoints(resolved.from, resolved.limit);
+    const checkpoints = await this.getCheckpointsData(query);
     return Promise.all(checkpoints.map(ch => this.getPublishedCheckpointFromCheckpointData(ch)));
   }
 
@@ -271,11 +250,14 @@ export abstract class ArchiverDataSourceBase
   }
 
   public async getCheckpointsData(query: CheckpointsQuery): Promise<CheckpointData[]> {
-    const resolved = await this.resolveCheckpointsQuery(query);
-    if (!resolved) {
-      return [];
+    if ('fromSlot' in query) {
+      return this.stores.blocks.getCheckpointsBySlot(query.fromSlot, query.limit, query.reverse ?? false);
     }
-    return this.stores.blocks.getRangeOfCheckpoints(resolved.from, resolved.limit);
+    if ('from' in query) {
+      return this.stores.blocks.getRangeOfCheckpoints(query.from, query.limit);
+    }
+    const numbers = await this.getCheckpointNumbersForEpoch(query.epoch);
+    return numbers.length > 0 ? this.stores.blocks.getRangeOfCheckpoints(numbers[0], numbers.length) : [];
   }
 
   public getProposedCheckpointData(query?: ProposedCheckpointQuery): Promise<ProposedCheckpointData | undefined> {

yarn-project/archiver/src/store/block_store.test.ts

@@ -1686,6 +1686,77 @@ describe('BlockStore', () => {
     });
   });
 
+  describe('getCheckpointsBySlot', () => {
+    // cp1: slot 5, blocks 1-2 | cp2: slot 8, blocks 3-5 | cp3: slot 12, block 6.
+    const addCheckpointsAtSlots = async () => {
+      const cp1 = makePublishedCheckpoint(
+        await Checkpoint.random(CheckpointNumber(1), { numBlocks: 2, startBlockNumber: 1, slotNumber: SlotNumber(5) }),
+        10,
+      );
+      const cp2 = makePublishedCheckpoint(
+        await Checkpoint.random(CheckpointNumber(2), {
+          numBlocks: 3,
+          startBlockNumber: 3,
+          previousArchive: cp1.checkpoint.blocks.at(-1)!.archive,
+          slotNumber: SlotNumber(8),
+        }),
+        11,
+      );
+      const cp3 = makePublishedCheckpoint(
+        await Checkpoint.random(CheckpointNumber(3), {
+          numBlocks: 1,
+          startBlockNumber: 6,
+          previousArchive: cp2.checkpoint.blocks.at(-1)!.archive,
+          slotNumber: SlotNumber(12),
+        }),
+        12,
+      );
+      await blockStore.addCheckpoints([cp1, cp2, cp3]);
+    };
+
+    const numbersBySlot = (slot: number, limit: number, reverse: boolean) =>
+      blockStore.getCheckpointsBySlot(SlotNumber(slot), limit, reverse).then(cps => cps.map(cp => cp.checkpointNumber));
+
+    it('returns empty array when no checkpoints exist', async () => {
+      expect(await numbersBySlot(10, 1, true)).toEqual([]);
+    });
+
+    it('returns the latest checkpoint at or before the slot when reverse (exact hit)', async () => {
+      await addCheckpointsAtSlots();
+      const [cp] = await blockStore.getCheckpointsBySlot(SlotNumber(8), 1, true);
+      expect(cp.checkpointNumber).toBe(2);
+      expect(cp.startBlock).toBe(3);
+      expect(cp.blockCount).toBe(3);
+    });
+
+    it('walks back to the nearest earlier checkpoint when the slot falls in a gap', async () => {
+      await addCheckpointsAtSlots();
+      // Slot 10 has no checkpoint; the nearest at or before is cp2 at slot 8.
+      expect(await numbersBySlot(10, 1, true)).toEqual([2]);
+    });
+
+    it('returns empty when reverse and the slot precedes the earliest checkpoint', async () => {
+      await addCheckpointsAtSlots();
+      expect(await numbersBySlot(4, 1, true)).toEqual([]);
+    });
+
+    it('returns multiple checkpoints nearest-first when reverse', async () => {
+      await addCheckpointsAtSlots();
+      expect(await numbersBySlot(12, 2, true)).toEqual([3, 2]);
+    });
+
+    it('returns the earliest checkpoint at or after the slot when forward', async () => {
+      await addCheckpointsAtSlots();
+      // Slot 6 has no checkpoint; the nearest at or after is cp2 at slot 8.
+      expect(await numbersBySlot(6, 1, false)).toEqual([2]);
+    });
+
+    it('returns multiple checkpoints ascending when forward', async () => {
+      await addCheckpointsAtSlots();
+      expect(await numbersBySlot(5, 3, false)).toEqual([1, 2, 3]);
+    });
+  });
+
   describe('getCheckpointedBlock', () => {
     beforeEach(async () => {
       await blockStore.addCheckpoints(publishedCheckpoints);

yarn-project/archiver/src/store/block_store.ts

@@ -627,6 +627,26 @@ export class BlockStore {
     return checkpoints;
   }
 
+  /**
+   * Returns up to `limit` checkpoints anchored at `fromSlot`, ordered nearest-first, walking the slot index.
+   * With `reverse`, takes the checkpoints at or before `fromSlot` (descending by slot); otherwise the
+   * checkpoints at or after it (ascending). `limit: 1, reverse: true` yields the latest checkpoint at or
+   * before the slot in a single range scan.
+   */
+  async getCheckpointsBySlot(fromSlot: SlotNumber, limit: number, reverse: boolean): Promise<CheckpointData[]> {
+    // The KV range bounds are direction-dependent: forward is [start, end), reverse is (start, end], so a
+    // reverse scan uses `end: fromSlot` (inclusive) with no +1 to include the checkpoint at fromSlot itself.
+    const range = reverse ? { end: fromSlot, reverse: true, limit } : { start: fromSlot, limit };
+    const result: CheckpointData[] = [];
+    for await (const [, checkpointNumber] of this.#slotToCheckpoint.entriesAsync(range)) {
+      const checkpointStorage = await this.#checkpoints.getAsync(checkpointNumber);
+      if (checkpointStorage) {
+        result.push(this.checkpointDataFromCheckpointStorage(checkpointStorage));
+      }
+    }
+    return result;
+  }
+
   /** Returns checkpoint data for all checkpoints whose slot falls within the given range (inclusive). */
   async getCheckpointDataForSlotRange(startSlot: SlotNumber, endSlot: SlotNumber): Promise<CheckpointData[]> {
     const result: CheckpointData[] = [];

yarn-project/archiver/src/test/mock_l2_block_source.ts

@@ -323,6 +323,13 @@ export class MockL2BlockSource implements L2BlockSource, ContractDataSource {
     if ('from' in query) {
       return this.checkpointList.slice(query.from - 1, query.from - 1 + query.limit);
     }
+    if ('fromSlot' in query) {
+      const matching = this.checkpointList.filter(c =>
+        query.reverse ? c.header.slotNumber <= query.fromSlot : c.header.slotNumber >= query.fromSlot,
+      );
+      const nearestFirst = query.reverse ? matching.reverse() : matching;
+      return nearestFirst.slice(0, query.limit);
+    }
     return this.getCheckpointsInEpoch(query.epoch);
   }