@lodestar/beacon-node 1.48.0-dev.a427d3dbb5 → 1.48.0-dev.acdde443d2

package/src/chain/archiveStore/utils/archiveBlocks.ts

@@ -134,6 +134,8 @@ export async function archiveBlocks(
       logger.verbose("Migrated blobSidecars from hot DB to cold DB", {...logCtx, migratedEntries});
     }
 
+    // Keep the normal LevelDB hot-to-cold flow for legacy columns. New columns are written
+    // directly to flat files, so this only moves fallback data left by older versions.
     if (finalizedPostFulu) {
       const migratedSlots = await migrateDataColumnSidecarsFromHotToColdDb(
         config,
@@ -142,7 +144,7 @@ export async function archiveBlocks(
         finalizedCanonicalBlocks,
         currentEpoch
       );
-      logger.verbose("Migrated dataColumnSidecars from hot DB to cold DB", {
+      logger.verbose("Migrated legacy dataColumnSidecars from hot DB to cold DB", {
         ...logCtx,
         migratedEntries: migratedSlots.length,
         slotRange: prettyPrintIndices(migratedSlots),
@@ -195,6 +197,23 @@ export async function archiveBlocks(
       slotRange: prettyPrintIndices(nonCanonicalSlots),
     };
 
+    const columnItems = finalizedNonCanonicalBlocks
+      // Gloas EMPTY and FULL variants share a block root. EMPTY has no sidecars, so deleting by its root could
+      // remove the canonical FULL variant's columns. Pre-Gloas blocks are always FULL.
+      .filter(
+        (summary) => config.getForkSeq(summary.slot) >= ForkSeq.fulu && summary.payloadStatus === PayloadStatus.FULL
+      )
+      .map((summary) => ({slot: summary.slot, blockRoot: summary.blockRoot}));
+    if (columnItems.length > 0) {
+      // Delete sidecars first so their block roots remain available to retry cleanup after a failure or crash.
+      await db.dataColumns.deleteMany(columnItems);
+      logger.verbose("Deleted non canonical data columns of blocks", {
+        ...logCtx,
+        blocks: columnItems.length,
+        slotRange: prettyPrintIndices(columnItems.map(({slot}) => slot).sort((a, b) => a - b)),
+      });
+    }
+
     await db.block.batchDelete(nonCanonicalBlockRoots);
     logger.verbose("Deleted non canonical blocks from hot DB", nonCanonicalLogCtx);
 
@@ -203,11 +222,6 @@ export async function archiveBlocks(
       logger.verbose("Deleted non canonical blobSidecars from hot DB", nonCanonicalLogCtx);
     }
 
-    if (finalizedPostFulu) {
-      await db.dataColumnSidecar.deleteMany(nonCanonicalBlockRoots);
-      logger.verbose("Deleted non canonical dataColumnSidecars from hot DB", nonCanonicalLogCtx);
-    }
-
     if (finalizedPostGloas) {
       await db.executionPayloadEnvelope.batchDelete(nonCanonicalBlockRoots);
       logger.verbose("Deleted non canonical executionPayloadEnvelopes from hot DB", nonCanonicalLogCtx);
@@ -245,23 +259,16 @@ export async function archiveBlocks(
       );
       const dataColumnSidecarsMinEpoch = currentEpoch - dataColumnSidecarsArchiveWindow;
       if (dataColumnSidecarsMinEpoch >= config.FULU_FORK_EPOCH) {
-        const prefixedKeys = await db.dataColumnSidecarArchive.keys({
-          // The `id` value `0` refers to the column index. So we want to fetch all sidecars less than zero column of `dataColumnSidecarsMinEpoch`
-          lt: {prefix: computeStartSlotAtEpoch(dataColumnSidecarsMinEpoch), id: 0},
-        });
-        // for each slot there could be multiple dataColumnSidecar, so we need to deduplicate it
-        const slotsToDelete = [...new Set(prefixedKeys.map(({prefix}) => prefix))].sort((a, b) => a - b);
-
-        if (slotsToDelete.length > 0) {
-          await db.dataColumnSidecarArchive.deleteMany(slotsToDelete);
+        const columnsPruneSlot = computeStartSlotAtEpoch(dataColumnSidecarsMinEpoch);
+        const prunedColumnSlots = await db.dataColumns.pruneBefore(columnsPruneSlot);
+        if (prunedColumnSlots.length > 0) {
           logger.verbose("dataColumnSidecars prune", {
             ...logCtx,
-            slotRange: prettyPrintIndices(slotsToDelete),
-            numOfSlots: slotsToDelete.length,
-            totalNumOfSidecars: prefixedKeys.length,
+            slotRange: prettyPrintIndices(prunedColumnSlots),
+            numOfSlots: prunedColumnSlots.length,
           });
         } else {
-          logger.verbose(`dataColumnSidecars prune: no entries before epoch ${dataColumnSidecarsMinEpoch}`, logCtx);
+          logger.verbose("dataColumnSidecars prune: no entries before slot", {...logCtx, slot: columnsPruneSlot});
         }
       } else {
         logger.verbose(
@@ -389,7 +396,6 @@ async function migrateBlobSidecarsFromHotToColdDb(
       )
     ).filter((e): e is KeyValue<Slot, Uint8Array> => e !== null);
 
-    // put to blockArchive db and delete block db
     await Promise.all([
       db.blobSidecarsArchive.batchPutBinary(canonicalBlobSidecarsEntries),
       db.blobSidecars.batchDelete(canonicalBlocks.map((block) => block.root)),
@@ -402,11 +408,9 @@ async function migrateBlobSidecarsFromHotToColdDb(
 
 // TODO: This function can be simplified further by reducing layers of promises in a loop
 /**
- * Post-gloas the data columns of a Gloas block are tied to its execution payload envelope —
- * columns only exist once the FULL variant of the block is in the proto-array. Pre-Gloas (Fulu)
- * blocks only have a FULL variant, so the `payloadStatus === FULL` filter passes them all.
- * Blocks whose canonical variant is PENDING/EMPTY are skipped here — their columns will be picked
- * up on a later run once the FULL variant appears in the ancestor walk.
+ * Post-gloas the data columns of a Gloas block are tied to its execution payload envelope.
+ * Columns only exist once the FULL variant of the block is in the proto-array. Pre-Gloas
+ * blocks only have a FULL variant, so the payload-status filter passes them all.
  */
 async function migrateDataColumnSidecarsFromHotToColdDb(
   config: ChainForkConfig,
@@ -428,32 +432,24 @@ async function migrateDataColumnSidecarsFromHotToColdDb(
     if (batch.length === 0) break;
 
     const promises: Promise<void>[] = [];
-
-    // load Buffer instead of ssz deserialized to improve performance
     for (const block of batch) {
-      const blockSlot = block.slot;
-      const blockEpoch = computeEpochAtSlot(blockSlot);
-
+      const blockEpoch = computeEpochAtSlot(block.slot);
       if (
-        config.getForkSeq(blockSlot) < ForkSeq.fulu ||
-        // if block is out of ${config.MIN_EPOCHS_FOR_DATA_COLUMN_SIDECARS_REQUESTS}, skip this step
+        config.getForkSeq(block.slot) < ForkSeq.fulu ||
         blockEpoch < currentEpoch - config.MIN_EPOCHS_FOR_DATA_COLUMN_SIDECARS_REQUESTS
       ) {
         continue;
       }
 
-      // Here we assume the data column sidecars are already in the hot db
       const dataColumnSidecarBytes = await fromAsync(db.dataColumnSidecar.valuesStreamBinary(block.root));
       if (dataColumnSidecarBytes.length === 0) {
-        // Empty stream: either the block has no blobs, or columns were already archived on a
-        // previous run (boundary block). Nothing to migrate.
         logger.debug("DataColumnSidecars in forkchoice but missing in hot db, could be already archived", {
           slot: block.slot,
           root: toRootHex(block.root),
         });
         continue;
       }
-      logger.verbose("Migrated dataColumnSidecars for block", {
+      logger.verbose("Migrated legacy dataColumnSidecars for block", {
         currentEpoch,
         slot: block.slot,
         root: toRootHex(block.root),
@@ -462,15 +458,14 @@ async function migrateDataColumnSidecarsFromHotToColdDb(
       promises.push(
         db.dataColumnSidecarArchive.putManyBinary(
           block.slot,
-          dataColumnSidecarBytes.map((p) => ({key: p.id, value: p.value}))
+          dataColumnSidecarBytes.map((entry) => ({key: entry.id, value: entry.value}))
         )
       );
       migratedSlots.push(block.slot);
     }
 
-    promises.push(db.dataColumnSidecar.deleteMany(batch.map((block) => block.root)));
-
     await Promise.all(promises);
+    await db.dataColumnSidecar.deleteMany(batch.map((block) => block.root));
   }
 
   // Ancestor walk is newest to oldest; sort ascending so `prettyPrintIndices` renders cleanly.

package/src/chain/blocks/writeBlockInputToDb.ts

@@ -1,6 +1,6 @@
-import {ForkPostDeneb, isForkPostDeneb} from "@lodestar/params";
+import {ForkPostDeneb, ForkPostFulu, isForkPostDeneb} from "@lodestar/params";
 import {SignedBeaconBlock} from "@lodestar/types";
-import {fromHex, toRootHex} from "@lodestar/utils";
+import {toRootHex} from "@lodestar/utils";
 import {getBlobKzgCommitments} from "../../util/dataColumns.js";
 import {BeaconChain} from "../chain.js";
 import {IBlockInput, IDataColumnsInput, isBlockInputBlobs, isBlockInputColumns} from "./blockInput/index.js";
@@ -76,7 +76,6 @@ async function writeBlockAndBlobsToDb(this: BeaconChain, blockInput: IBlockInput
  */
 export async function writeDataColumnsToDb(this: BeaconChain, blockInput: IDataColumnsInput): Promise<void> {
   const {slot, blockRootHex} = blockInput;
-  const blockRoot = fromHex(blockRootHex);
 
   if (!blockInput.hasComputedAllData()) {
     // Supernodes may only have a subset of the data columns by the time the block begins to be imported
@@ -89,25 +88,19 @@ export async function writeDataColumnsToDb(this: BeaconChain, blockInput: IDataC
 
   const {custodyColumns} = this.custodyConfig;
   const dataColumnSidecars = blockInput.getCustodyColumns();
+  const dataColumnSidecarType = this.config.getForkTypes<ForkPostFulu>(slot).DataColumnSidecar;
 
-  const binaryPuts: {key: number; value: Uint8Array}[] = [];
-  const nonbinaryPuts = [];
+  const binaryColumns: {index: number; data: Uint8Array}[] = [];
   for (const dataColumnSidecar of dataColumnSidecars) {
-    // skip reserializing column if we already have it
     const serialized = this.serializedCache.get(dataColumnSidecar);
-    if (serialized) {
-      binaryPuts.push({key: dataColumnSidecar.index, value: serialized});
-    } else {
-      nonbinaryPuts.push(dataColumnSidecar);
-    }
+    binaryColumns.push({
+      index: dataColumnSidecar.index,
+      data: serialized ?? dataColumnSidecarType.serialize(dataColumnSidecar),
+    });
   }
+  await this.db.dataColumns.putManyBinary({slot, blockRoot: blockRootHex}, binaryColumns);
 
-  await Promise.all([
-    this.db.dataColumnSidecar.putManyBinary(blockRoot, binaryPuts),
-    this.db.dataColumnSidecar.putMany(blockRoot, nonbinaryPuts),
-  ]);
-
-  this.logger.debug("Persisted dataColumnSidecars to hot DB", {
+  this.logger.debug("Persisted dataColumnSidecars", {
     slot,
     root: blockRootHex,
     dataColumnSidecars: dataColumnSidecars.length,

package/src/chain/chain.ts

@@ -268,6 +268,7 @@ export class BeaconChain implements IBeaconChain {
       db,
       dbName,
       dataDir,
+      dataColumnDir,
       logger,
       processShutdownCallback,
       clock,
@@ -285,6 +286,7 @@ export class BeaconChain implements IBeaconChain {
       db: IBeaconDb;
       dbName: string;
       dataDir: string;
+      dataColumnDir?: string;
       logger: Logger;
       processShutdownCallback: ProcessShutdownCallback;
       /** Used for testing to supply fake clock */
@@ -505,7 +507,12 @@ export class BeaconChain implements IBeaconChain {
 
     this.archiveStore = new ArchiveStore(
       {db, chain: this, logger: logger as LoggerNode, metrics},
-      {...opts, dbName, anchorState: {finalizedCheckpoint: anchorState.finalizedCheckpoint}},
+      {
+        ...opts,
+        dbName,
+        dataColumnDir: dataColumnDir ?? path.join(dataDir, "data_columns"),
+        anchorState: {finalizedCheckpoint: anchorState.finalizedCheckpoint},
+      },
       signal
     );
 
@@ -969,12 +976,15 @@ export class BeaconChain implements IBeaconChain {
 
   async getDataColumnSidecars(blockSlot: Slot, blockRootHex: string): Promise<DataColumnSidecar[]> {
     const fork = this.config.getForkName(blockSlot);
+    const sidecarsByIndex = new Map<number, DataColumnSidecar>();
 
     if (isForkPostGloas(fork)) {
       // After gloas, columns are tracked in PayloadEnvelopeInput
       const payloadInput = this.seenPayloadEnvelopeInputCache.get(blockRootHex);
       if (payloadInput) {
-        return payloadInput.getAllColumns();
+        for (const sidecar of payloadInput.getAllColumns()) {
+          sidecarsByIndex.set(sidecar.index, sidecar);
+        }
       }
     } else {
       // Before gloas, columns are tracked in BlockInput
@@ -983,16 +993,17 @@ export class BeaconChain implements IBeaconChain {
         if (!isBlockInputColumns(blockInput)) {
           throw new Error(`Expected block input to have columns: slot=${blockSlot} root=${blockRootHex}`);
         }
-        return blockInput.getAllColumns();
+        for (const sidecar of blockInput.getAllColumns()) {
+          sidecarsByIndex.set(sidecar.index, sidecar);
+        }
       }
     }
 
-    const sidecarsUnfinalized = await this.db.dataColumnSidecar.values(fromHex(blockRootHex));
-    if (sidecarsUnfinalized.length > 0) {
-      return sidecarsUnfinalized;
+    for (const sidecar of await this.db.dataColumns.getAll({slot: blockSlot, blockRoot: blockRootHex})) {
+      if (!sidecarsByIndex.has(sidecar.index)) sidecarsByIndex.set(sidecar.index, sidecar);
     }
-    const sidecarsFinalized = await this.db.dataColumnSidecarArchive.values(blockSlot);
-    return sidecarsFinalized;
+
+    return [...sidecarsByIndex.values()].sort((a, b) => a.index - b.index);
   }
 
   async getSerializedDataColumnSidecars(
@@ -1001,22 +1012,25 @@ export class BeaconChain implements IBeaconChain {
     indices: number[]
   ): Promise<(Uint8Array | undefined)[]> {
     const fork = this.config.getForkName(blockSlot);
+    const dataColumnSidecars: (Uint8Array | undefined)[] = indices.map(() => undefined);
 
     if (isForkPostGloas(fork)) {
       // After gloas, columns are tracked in PayloadEnvelopeInput
       const payloadInput = this.seenPayloadEnvelopeInputCache.get(blockRootHex);
       if (payloadInput) {
-        return indices.map((index) => {
+        for (let i = 0; i < indices.length; i++) {
+          const index = indices[i];
           const sidecar = payloadInput.getColumn(index);
           if (!sidecar) {
-            return undefined;
+            continue;
           }
           const serialized = this.serializedCache.get(sidecar);
           if (serialized) {
-            return serialized;
+            dataColumnSidecars[i] = serialized;
+          } else {
+            dataColumnSidecars[i] = sszTypesFor(fork as ForkPostGloas).DataColumnSidecar.serialize(sidecar);
           }
-          return sszTypesFor(fork as ForkPostGloas).DataColumnSidecar.serialize(sidecar);
-        });
+        }
       }
     } else {
       // Before gloas, columns are tracked in BlockInput
@@ -1025,26 +1039,42 @@ export class BeaconChain implements IBeaconChain {
         if (!isBlockInputColumns(blockInput)) {
           throw new Error(`Expected block input to have columns: slot=${blockSlot} root=${blockRootHex}`);
         }
-        return indices.map((index) => {
+        for (let i = 0; i < indices.length; i++) {
+          const index = indices[i];
           const sidecar = blockInput.getColumn(index);
           if (!sidecar) {
-            return undefined;
+            continue;
           }
           const serialized = this.serializedCache.get(sidecar);
           if (serialized) {
-            return serialized;
+            dataColumnSidecars[i] = serialized;
+          } else {
+            dataColumnSidecars[i] = sszTypesFor(blockInput.forkName as ForkPostFulu).DataColumnSidecar.serialize(
+              sidecar
+            );
           }
-          return sszTypesFor(blockInput.forkName as ForkPostFulu).DataColumnSidecar.serialize(sidecar);
-        });
+        }
       }
     }
 
-    const sidecarsUnfinalized = await this.db.dataColumnSidecar.getManyBinary(fromHex(blockRootHex), indices);
-    if (sidecarsUnfinalized.some((sidecar) => sidecar != null)) {
-      return sidecarsUnfinalized;
+    const missingPositions = dataColumnSidecars
+      .map((sidecar, position) => (sidecar === undefined ? position : -1))
+      .filter((position) => position !== -1);
+
+    if (missingPositions.length > 0) {
+      const persistedSidecars = await this.db.dataColumns.getManyBinary(
+        {slot: blockSlot, blockRoot: blockRootHex},
+        missingPositions.map((position) => indices[position])
+      );
+      for (let i = 0; i < missingPositions.length; i++) {
+        const sidecar = persistedSidecars[i];
+        if (sidecar !== undefined) {
+          dataColumnSidecars[missingPositions[i]] = sidecar;
+        }
+      }
     }
-    const sidecarsFinalized = await this.db.dataColumnSidecarArchive.getManyBinary(blockSlot, indices);
-    return sidecarsFinalized;
+
+    return dataColumnSidecars;
   }
 
   async produceCommonBlockBody(blockAttributes: BlockAttributes): Promise<CommonBlockBody> {

package/src/db/beacon.ts

@@ -1,6 +1,11 @@
 import {ChainForkConfig} from "@lodestar/config";
 import {Db, LevelDbControllerMetrics, encodeKey} from "@lodestar/db";
+import {Slot} from "@lodestar/types";
+import {Logger} from "@lodestar/utils";
 import {Bucket} from "./buckets.js";
+import {type IDataColumnStore, LegacyDataColumnStore} from "./dataColumnStore.js";
+import {FlatFileStore} from "./flatFileStore/flatFileStore.js";
+import type {FlatFileStoreMetrics} from "./flatFileStore/metrics.js";
 import {IBeaconDb} from "./interface.js";
 import {CheckpointStateRepository} from "./repositories/checkpointState.js";
 import {
@@ -24,9 +29,10 @@ import {
   VoluntaryExitRepository,
 } from "./repositories/index.js";
 
-export type BeaconDbModules = {
-  config: ChainForkConfig;
-  db: Db;
+export type BeaconDbOpts = {
+  dataColumnDir: string;
+  logger: Logger;
+  metrics?: FlatFileStoreMetrics | null;
 };
 
 export class BeaconDb implements IBeaconDb {
@@ -57,9 +63,14 @@ export class BeaconDb implements IBeaconDb {
 
   backfilledRanges: BackfilledRanges;
 
+  readonly dataColumns: IDataColumnStore;
+  lastLegacyArchiveSlot: Slot | null = null;
+  private readonly flatFileStore: FlatFileStore;
+
   constructor(
     config: ChainForkConfig,
-    protected readonly db: Db
+    protected readonly db: Db,
+    opts: BeaconDbOpts
   ) {
     // Warning: If code is ever run in the constructor, must change this stub to not extend 'packages/beacon-node/test/utils/stub/beaconDb.ts' -
     this.block = new BlockRepository(config, db);
@@ -87,14 +98,30 @@ export class BeaconDb implements IBeaconDb {
     this.syncCommitteeWitness = new SyncCommitteeWitnessRepository(config, db);
 
     this.backfilledRanges = new BackfilledRanges(config, db);
+
+    this.flatFileStore = new FlatFileStore(opts.dataColumnDir, config, opts.logger, opts.metrics);
+    this.dataColumns = new LegacyDataColumnStore(
+      this.flatFileStore,
+      this.dataColumnSidecar,
+      this.dataColumnSidecarArchive,
+      this.blockArchive
+    );
+  }
+
+  async init(): Promise<void> {
+    await this.flatFileStore.init();
+    const [lastLegacyKey] = await this.dataColumnSidecarArchive.keys({reverse: true, limit: 1});
+    this.lastLegacyArchiveSlot = lastLegacyKey?.prefix ?? null;
   }
 
-  close(): Promise<void> {
+  async close(): Promise<void> {
+    await this.flatFileStore.close();
     return this.db.close();
   }
 
-  setMetrics(metrics: LevelDbControllerMetrics): void {
+  setMetrics(metrics: LevelDbControllerMetrics, flatFileStoreMetrics: FlatFileStoreMetrics | null = null): void {
     this.db.setMetrics(metrics);
+    this.flatFileStore.setMetrics(flatFileStoreMetrics);
   }
 
   async pruneHotDb(): Promise<void> {

package/src/db/dataColumnStore.ts

@@ -0,0 +1,113 @@
+import {ColumnIndex, DataColumnSidecar, RootHex, Slot} from "@lodestar/types";
+import {fromHex} from "@lodestar/utils";
+import type {IFlatFileStore} from "./flatFileStore/interface.js";
+import type {
+  BlockArchiveRepository,
+  DataColumnSidecarArchiveRepository,
+  DataColumnSidecarRepository,
+} from "./repositories/index.js";
+
+export type DataColumnKey = {slot: Slot; blockRoot: RootHex};
+export type IndexedDataColumnBytes = {index: ColumnIndex; data: Uint8Array};
+
+type LegacyHotDataColumnStore = Pick<DataColumnSidecarRepository, "values" | "getManyBinary" | "deleteMany">;
+type LegacyArchiveDataColumnStore = Pick<
+  DataColumnSidecarArchiveRepository,
+  "values" | "getManyBinary" | "keys" | "deleteMany"
+>;
+type BlockRootIndex = Pick<BlockArchiveRepository, "getSlotByRoot">;
+
+export interface IDataColumnStore {
+  getAll(key: DataColumnKey): Promise<DataColumnSidecar[]>;
+  getManyBinary(key: DataColumnKey, indices: ColumnIndex[]): Promise<(Uint8Array | undefined)[]>;
+  putManyBinary(key: DataColumnKey, columns: IndexedDataColumnBytes[]): Promise<void>;
+  deleteMany(keys: DataColumnKey[]): Promise<void>;
+  pruneBefore(slot: Slot): Promise<Slot[]>;
+}
+
+/**
+ * Bridges pre-flat-file LevelDB columns during the supported in-place upgrade window.
+ * Remove the legacy repositories after upgrades from the last pre-flat-file release are no longer supported.
+ */
+export class LegacyDataColumnStore implements IDataColumnStore {
+  constructor(
+    private readonly flatFiles: IFlatFileStore,
+    private readonly legacyHot: LegacyHotDataColumnStore,
+    private readonly legacyArchive: LegacyArchiveDataColumnStore,
+    private readonly blockArchive: BlockRootIndex
+  ) {}
+
+  async getAll({slot, blockRoot}: DataColumnKey): Promise<DataColumnSidecar[]> {
+    const sidecars = await this.flatFiles.getDataColumns(slot, blockRoot);
+    if (sidecars.length > 0) return sidecars;
+
+    const sidecarsByIndex = new Map<ColumnIndex, DataColumnSidecar>();
+    const root = fromHex(blockRoot);
+    for (const sidecar of await this.legacyHot.values(root)) {
+      if (!sidecarsByIndex.has(sidecar.index)) sidecarsByIndex.set(sidecar.index, sidecar);
+    }
+
+    if ((await this.blockArchive.getSlotByRoot(root)) === slot) {
+      for (const sidecar of await this.legacyArchive.values(slot)) {
+        if (!sidecarsByIndex.has(sidecar.index)) sidecarsByIndex.set(sidecar.index, sidecar);
+      }
+    }
+
+    return [...sidecarsByIndex.values()].sort((a, b) => a.index - b.index);
+  }
+
+  async getManyBinary({slot, blockRoot}: DataColumnKey, indices: ColumnIndex[]): Promise<(Uint8Array | undefined)[]> {
+    const flatFileSidecars = await this.flatFiles.getDataColumnsBinary(slot, blockRoot, indices);
+    if (flatFileSidecars !== null) return flatFileSidecars;
+    if (indices.length === 0) return [];
+
+    const root = fromHex(blockRoot);
+    const result = await this.legacyHot.getManyBinary(root, indices);
+
+    const missingPositions = getMissingPositions(result);
+    if (missingPositions.length === 0 || (await this.blockArchive.getSlotByRoot(root)) !== slot) return result;
+
+    const archivedSidecars = await this.legacyArchive.getManyBinary(
+      slot,
+      missingPositions.map((position) => indices[position])
+    );
+    fillMissing(result, missingPositions, archivedSidecars);
+    return result;
+  }
+
+  async putManyBinary({slot, blockRoot}: DataColumnKey, columns: IndexedDataColumnBytes[]): Promise<void> {
+    await this.flatFiles.putDataColumnsBinary(slot, blockRoot, columns);
+  }
+
+  async deleteMany(keys: DataColumnKey[]): Promise<void> {
+    await this.flatFiles.deleteMany(keys);
+    await this.legacyHot.deleteMany(keys.map(({blockRoot}) => fromHex(blockRoot)));
+  }
+
+  async pruneBefore(slot: Slot): Promise<Slot[]> {
+    const flatFileSlots = await this.flatFiles.pruneBefore(slot);
+    const prefixedKeys = await this.legacyArchive.keys({lt: {prefix: slot, id: 0}});
+    const slots = [...new Set(prefixedKeys.map(({prefix}) => prefix))];
+    if (slots.length > 0) await this.legacyArchive.deleteMany(slots);
+    return [...new Set([...flatFileSlots, ...slots])].sort((a, b) => a - b);
+  }
+}
+
+function getMissingPositions(sidecars: (Uint8Array | undefined)[]): number[] {
+  const positions: number[] = [];
+  for (let i = 0; i < sidecars.length; i++) {
+    if (sidecars[i] === undefined) positions.push(i);
+  }
+  return positions;
+}
+
+function fillMissing(
+  result: (Uint8Array | undefined)[],
+  missingPositions: number[],
+  sidecars: (Uint8Array | null | undefined)[]
+): void {
+  for (let i = 0; i < missingPositions.length; i++) {
+    const sidecar = sidecars[i];
+    if (sidecar != null) result[missingPositions[i]] = sidecar;
+  }
+}

package/src/db/flatFileStore/atomicWrite.ts

@@ -0,0 +1,65 @@
+import {mkdir, open, rename, rm} from "node:fs/promises";
+import path from "node:path";
+
+const pendingDirectorySyncs = new Map<string, string[]>();
+
+/**
+ * Atomic write: write to `.part` temp file -> datasync -> rename to target.
+ * This guarantees crash-safe writes — if the process crashes mid-write,
+ * only the `.part` file is corrupted, never the target.
+ */
+export async function atomicWrite(targetPath: string, data: Uint8Array): Promise<void> {
+  const dir = path.dirname(targetPath);
+  const partPath = `${targetPath}.part-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  await mkdirDurable(dir);
+
+  try {
+    const fd = await open(partPath, "wx");
+    try {
+      await fd.writeFile(data);
+      await fd.datasync();
+    } finally {
+      await fd.close();
+    }
+
+    await rename(partPath, targetPath);
+
+    // Ensure rename metadata is durable on crash.
+    await syncDirectory(dir);
+  } catch (e) {
+    await rm(partPath, {force: true}).catch(() => {});
+    throw e;
+  }
+}
+
+export async function mkdirDurable(dir: string): Promise<void> {
+  const targetDir = path.resolve(dir);
+  let directoriesToSync = pendingDirectorySyncs.get(targetDir);
+  if (directoriesToSync === undefined) {
+    const firstCreatedDir = await mkdir(targetDir, {recursive: true});
+    if (firstCreatedDir === undefined) return;
+
+    let createdDir = path.resolve(firstCreatedDir);
+    directoriesToSync = [path.dirname(createdDir)];
+    while (createdDir !== targetDir) {
+      directoriesToSync.push(createdDir);
+      const [nextSegment] = path.relative(createdDir, targetDir).split(path.sep);
+      createdDir = path.join(createdDir, nextSegment);
+    }
+    pendingDirectorySyncs.set(targetDir, directoriesToSync);
+  }
+
+  for (const directory of directoriesToSync) {
+    await syncDirectory(directory);
+  }
+  pendingDirectorySyncs.delete(targetDir);
+}
+
+async function syncDirectory(dir: string): Promise<void> {
+  const dirFd = await open(dir, "r");
+  try {
+    await dirFd.sync();
+  } finally {
+    await dirFd.close();
+  }
+}