@lodestar/beacon-node 1.47.0-dev.0bcaaaebb5 → 1.47.0-dev.101e2c290d

package/lib/chain/seenCache/seenPayloadEnvelopeInput.js

@@ -1,9 +1,14 @@
 import { PayloadStatus } from "@lodestar/fork-choice";
+import { SLOTS_PER_EPOCH, isForkPostGloas } from "@lodestar/params";
 import { computeStartSlotAtEpoch } from "@lodestar/state-transition";
+import { fromHex } from "@lodestar/utils";
+import { MAX_LOOK_AHEAD_EPOCHS } from "../../sync/constants.js";
 import { isDaOutOfRange } from "../blocks/blockInput/index.js";
-import { PayloadEnvelopeInput } from "../blocks/payloadEnvelopeInput/index.js";
+import { PayloadEnvelopeInput, PayloadEnvelopeInputSource, } from "../blocks/payloadEnvelopeInput/index.js";
 import { ChainEvent } from "../emitter.js";
 export { PayloadEnvelopeInput } from "../blocks/payloadEnvelopeInput/index.js";
+// Bound this cache by this max size, this is the same to SeenBlockInput
+const MAX_PAYLOAD_ENVELOPE_INPUT_CACHE_SIZE = (MAX_LOOK_AHEAD_EPOCHS + 1) * SLOTS_PER_EPOCH;
 /**
  * Cache for tracking PayloadEnvelopeInput instances, keyed by beacon block root.
  *
@@ -20,16 +25,24 @@ export class SeenPayloadEnvelopeInput {
     chainEvents;
     signal;
     serializedCache;
+    db;
+    seenBlockInputCache;
+    custodyConfig;
     metrics;
     logger;
     payloadInputs = new Map();
-    constructor({ config, clock, forkChoice, chainEvents, signal, serializedCache, metrics, logger, }) {
+    // Dedup concurrent DB reloads of the same root so callers share one reconstructed object.
+    reloading = new Map();
+    constructor({ config, clock, forkChoice, chainEvents, signal, serializedCache, db, seenBlockInputCache, custodyConfig, metrics, logger, }) {
         this.config = config;
         this.clock = clock;
         this.forkChoice = forkChoice;
         this.chainEvents = chainEvents;
         this.signal = signal;
         this.serializedCache = serializedCache;
+        this.db = db;
+        this.seenBlockInputCache = seenBlockInputCache;
+        this.custodyConfig = custodyConfig;
         this.metrics = metrics;
         this.logger = logger;
         if (metrics) {
@@ -48,7 +61,7 @@ export class SeenPayloadEnvelopeInput {
         let deletedCount = 0;
         for (const [, input] of this.payloadInputs) {
             if (input.slot < finalizedSlot) {
-                this.evictPayloadInput(input);
+                this.evictPayloadInput(input, "finalized");
                 deletedCount++;
             }
         }
@@ -70,12 +83,13 @@ export class SeenPayloadEnvelopeInput {
         const daOutOfRange = isDaOutOfRange(this.config, props.forkName, props.block.message.slot, this.clock.currentEpoch);
         const input = PayloadEnvelopeInput.createFromBlock({ ...props, daOutOfRange });
         this.payloadInputs.set(props.blockRootHex, input);
-        this.metrics?.seenCache.payloadEnvelopeInput.created.inc();
+        this.metrics?.seenCache.payloadEnvelopeInput.created.inc({ source: props.source });
         this.logger?.verbose("SeenPayloadEnvelopeInput.add created new entry", {
             slot: input.slot,
             root: props.blockRootHex,
             daOutOfRange,
         });
+        this.pruneToMaxSize();
         return input;
     }
     /**
@@ -90,17 +104,87 @@ export class SeenPayloadEnvelopeInput {
         const daOutOfRange = isDaOutOfRange(this.config, props.forkName, props.slot, this.clock.currentEpoch);
         const input = PayloadEnvelopeInput.createFromBid({ ...props, daOutOfRange });
         this.payloadInputs.set(props.blockRootHex, input);
-        this.metrics?.seenCache.payloadEnvelopeInput.created.inc();
+        this.metrics?.seenCache.payloadEnvelopeInput.created.inc({ source: props.source });
         this.logger?.verbose("SeenPayloadEnvelopeInput.addFromBid created new entry", {
             slot: input.slot,
             root: props.blockRootHex,
             daOutOfRange,
         });
+        this.pruneToMaxSize();
         return input;
     }
     get(blockRootHex) {
         return this.payloadInputs.get(blockRootHex);
     }
+    /**
+     * Like `get()`, but on a cache miss reconstruct the shell (bid + versionedHashes) from the block
+     * in `seenBlockInputCache` or the hot DB.
+     * This api is meant for BlockInputSync when a late/weird payloads for old blocks
+     *
+     * NOTE: the reconstructed entry is always EMPTY even when the block is actually FULL (its
+     * payload envelope + columns persisted in the DB). The consumer should consult fork choice if it needs to.
+     */
+    async getOrReload(blockRootHex) {
+        const existing = this.payloadInputs.get(blockRootHex);
+        if (existing !== undefined) {
+            return existing;
+        }
+        // Without this dedup, two concurrent misses each db.block.get + createFromBlock a DIFFERENT shell
+        // for the same root; processPayloadEnvelopeJob's WeakMap (keyed by object) can't dedup the import.
+        const inflight = this.reloading.get(blockRootHex);
+        if (inflight !== undefined) {
+            return inflight;
+        }
+        const promise = this.reloadFromDb(blockRootHex);
+        this.reloading.set(blockRootHex, promise);
+        try {
+            return await promise;
+        }
+        finally {
+            this.reloading.delete(blockRootHex);
+        }
+    }
+    async reloadFromDb(blockRootHex) {
+        // Only recover unfinalized, fork-choice-known blocks. Do not read the finalized archive. The gate
+        // also filters out un-imported blocks that may sit in seenBlockInputCache before validation.
+        if (!this.forkChoice.hasBlockHex(blockRootHex)) {
+            return undefined;
+        }
+        // In-memory first: persistBlockInput writes db.block THEN prunes seenBlockInputCache, so a
+        // just-imported block whose async write (unfinalizedBlockWrites) has not flushed yet is still here;
+        // older blocks (already pruned from the cache) fall through to the hot db.
+        const cachedBlockInput = this.seenBlockInputCache.get(blockRootHex);
+        const block = cachedBlockInput?.hasBlock()
+            ? cachedBlockInput.getBlock()
+            : await this.db.block.get(fromHex(blockRootHex));
+        if (block == null) {
+            return undefined;
+        }
+        const forkName = this.config.getForkName(block.message.slot);
+        if (!isForkPostGloas(forkName)) {
+            return undefined;
+        }
+        const daOutOfRange = isDaOutOfRange(this.config, forkName, block.message.slot, this.clock.currentEpoch);
+        const input = PayloadEnvelopeInput.createFromBlock({
+            blockRootHex,
+            block: block,
+            forkName,
+            sampledColumns: this.custodyConfig.sampledColumns,
+            custodyColumns: this.custodyConfig.custodyColumns,
+            seenTimestampSec: Date.now() / 1000,
+            source: PayloadEnvelopeInputSource.reload,
+            daOutOfRange,
+        });
+        this.payloadInputs.set(blockRootHex, input);
+        this.metrics?.seenCache.payloadEnvelopeInput.created.inc({ source: PayloadEnvelopeInputSource.reload });
+        this.logger?.verbose("SeenPayloadEnvelopeInput.getOrReload reconstructed entry from db", {
+            slot: input.slot,
+            root: blockRootHex,
+        });
+        // Set above (entry is at the back of the insertion order), so the cap never evicts what we just reloaded.
+        this.pruneToMaxSize();
+        return input;
+    }
     hasPayload(blockRootHex) {
         return this.payloadInputs.get(blockRootHex)?.hasPayloadEnvelope() ?? false;
     }
@@ -110,8 +194,7 @@ export class SeenPayloadEnvelopeInput {
     prune(blockRootHex) {
         const input = this.payloadInputs.get(blockRootHex);
         if (input) {
-            this.evictPayloadInput(input);
-            this.logger?.verbose("SeenPayloadEnvelopeInput.prune deleted", { slot: input.slot, root: blockRootHex });
+            this.evictPayloadInput(input, "prune");
         }
     }
     pruneBelowParent(parentBlock) {
@@ -124,16 +207,41 @@ export class SeenPayloadEnvelopeInput {
                 // ...and don't evict while columns are still being gathered: writeDataColumnsToDb awaits the
                 // same hasComputedAllData() before persisting. Such entries are pruned by a later call.
                 if (input?.hasComputedAllData()) {
-                    this.evictPayloadInput(input);
-                    this.logger?.verbose("SeenPayloadEnvelopeInput.pruneBelowParent deleted", {
-                        slot: block.slot,
-                        root: block.blockRoot,
-                    });
+                    this.evictPayloadInput(input, "belowParent");
                 }
             }
         }
     }
-    evictPayloadInput(payloadInput) {
+    /**
+     * Bound this cache to have at most MAX_PAYLOAD_ENVELOPE_INPUT_CACHE_SIZE items.
+     * Evicts by insertion order so a just-reloaded old-slot entry is not evicted right after.
+     * On unstable network, we may need to query an evicted item, UnknownBlockInput will recover
+     * it from db via getOrReload() api. Runs after every single insert, so it evicts ~1 per call.
+     */
+    pruneToMaxSize() {
+        let evicted = 0;
+        for (const input of this.payloadInputs.values()) {
+            if (this.payloadInputs.size <= MAX_PAYLOAD_ENVELOPE_INPUT_CACHE_SIZE) {
+                break;
+            }
+            this.evictPayloadInput(input, "cap");
+            evicted++;
+        }
+        if (evicted > 0) {
+            this.logger?.debug("SeenPayloadEnvelopeInput.pruneToMaxSize evicted", {
+                evicted,
+                size: this.payloadInputs.size,
+                max: MAX_PAYLOAD_ENVELOPE_INPUT_CACHE_SIZE,
+            });
+        }
+    }
+    evictPayloadInput(payloadInput, reason) {
+        this.metrics?.seenCache.payloadEnvelopeInput.pruned.inc({ reason });
+        this.logger?.debug("SeenPayloadEnvelopeInput evicted", {
+            slot: payloadInput.slot,
+            root: payloadInput.blockRootHex,
+            reason,
+        });
         this.serializedCache.delete(payloadInput.getSerializedCacheKeys());
         this.payloadInputs.delete(payloadInput.blockRootHex);
     }

package/lib/chain/seenCache/seenPayloadEnvelopeInput.js.map

@@ -1 +1 @@
-{"version":3,"file":"seenPayloadEnvelopeInput.js","sourceRoot":"","sources":["../../../src/chain/seenCache/seenPayloadEnvelopeInput.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"seenPayloadEnvelopeInput.js","sourceRoot":"","sources":["../../../src/chain/seenCache/seenPayloadEnvelopeInput.ts"],"names":[],"mappings":"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"}

package/lib/chain/stateCache/fifoBlockStateCache.d.ts

@@ -66,13 +66,17 @@ export declare class FIFOBlockStateCache implements BlockStateCache {
      */
     add(item: IBeaconStateView, isHead?: boolean): void;
     get size(): number;
+    /**
+     * On a checkpoint event, prune the cache while keeping the head state.
+     */
+    onCheckpoint(headStateRootHex: string): void;
     /**
      * Prune the cache from tail to keep the most recent n states consistently.
      * The tail of the list is the oldest state, in case regen adds back the same state,
      * it should stay next to head so that it won't be pruned right away.
      * The FIFO cache helps with this.
      */
-    prune(lastAddedKey: string): void;
+    private prune;
     /**
      * ONLY FOR DEBUGGING PURPOSES. For lodestar debug API.
      */

package/lib/chain/stateCache/fifoBlockStateCache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fifoBlockStateCache.d.ts","sourceRoot":"","sources":["../../../src/chain/stateCache/fifoBlockStateCache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,MAAM,EAAC,MAAM,eAAe,CAAC;AACrC,OAAO,EAAC,gBAAgB,EAAC,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAC,OAAO,EAAC,MAAM,iBAAiB,CAAC;AAExC,OAAO,EAAC,OAAO,EAAC,MAAM,wBAAwB,CAAC;AAG/C,OAAO,EAAC,eAAe,EAAC,MAAM,YAAY,CAAC;AAE3C,MAAM,MAAM,uBAAuB,GAAG;IACpC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;IAC7D;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2C;IAEnE,YAAY,IAAI,EAAE,uBAAuB,EAAE,EAAC,OAAO,EAAC,EAAE;QAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;KAAC,EAQ/E;IAED;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAIhD;IAED;;;;OAIG;IACH,YAAY,IAAI,gBAAgB,CAU/B;IAED;;OAEG;IACH,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,GAAG,IAAI,CAW7C;IAED;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,UAAQ,GAAG,IAAI,CA+BhD;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;OAKG;IACH,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAehC;IAED;;OAEG;IACH,KAAK,IAAI,IAAI,CAEZ;IAED,0DAA0D;IAC1D,WAAW,IAAI,MAAM,CAAC,QAAQ,CAAC,cAAc,EAAE,CAQ9C;IAED,SAAS,IAAI,gBAAgB,CAAC,gBAAgB,CAAC,CAE9C;IAED;;OAEG;IACH,YAAY,IAAI,MAAM,EAAE,CAEvB;CACF"}
+{"version":3,"file":"fifoBlockStateCache.d.ts","sourceRoot":"","sources":["../../../src/chain/stateCache/fifoBlockStateCache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,MAAM,EAAC,MAAM,eAAe,CAAC;AACrC,OAAO,EAAC,gBAAgB,EAAC,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAC,OAAO,EAAC,MAAM,iBAAiB,CAAC;AAExC,OAAO,EAAC,OAAO,EAAC,MAAM,wBAAwB,CAAC;AAG/C,OAAO,EAAC,eAAe,EAAC,MAAM,YAAY,CAAC;AAE3C,MAAM,MAAM,uBAAuB,GAAG;IACpC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;IAC7D;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2C;IAEnE,YAAY,IAAI,EAAE,uBAAuB,EAAE,EAAC,OAAO,EAAC,EAAE;QAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;KAAC,EAQ/E;IAED;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAIhD;IAED;;;;OAIG;IACH,YAAY,IAAI,gBAAgB,CAU/B;IAED;;OAEG;IACH,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,GAAG,IAAI,CAW7C;IAED;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,UAAQ,GAAG,IAAI,CA+BhD;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,YAAY,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAE3C;IAED;;;;;OAKG;IACH,OAAO,CAAC,KAAK;IAiBb;;OAEG;IACH,KAAK,IAAI,IAAI,CAEZ;IAED,0DAA0D;IAC1D,WAAW,IAAI,MAAM,CAAC,QAAQ,CAAC,cAAc,EAAE,CAQ9C;IAED,SAAS,IAAI,gBAAgB,CAAC,gBAAgB,CAAC,CAE9C;IAED;;OAEG;IACH,YAAY,IAAI,MAAM,EAAE,CAEvB;CACF"}

package/lib/chain/stateCache/fifoBlockStateCache.js

@@ -124,6 +124,12 @@ export class FIFOBlockStateCache {
     get size() {
         return this.cache.size;
     }
+    /**
+     * On a checkpoint event, prune the cache while keeping the head state.
+     */
+    onCheckpoint(headStateRootHex) {
+        this.prune(headStateRootHex);
+    }
     /**
      * Prune the cache from tail to keep the most recent n states consistently.
      * The tail of the list is the oldest state, in case regen adds back the same state,

package/lib/chain/stateCache/fifoBlockStateCache.js.map

@@ -1 +1 @@
-{"version":3,"file":"fifoBlockStateCache.js","sourceRoot":"","sources":["../../../src/chain/stateCache/fifoBlockStateCache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fifoBlockStateCache.js","sourceRoot":"","sources":["../../../src/chain/stateCache/fifoBlockStateCache.ts"],"names":[],"mappings":"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"}

package/lib/chain/stateCache/persistentCheckpointsCache.d.ts

@@ -11,7 +11,11 @@ import { BlockStateCache, CheckpointHex, CheckpointStateCache } from "./types.js
 export type PersistentCheckpointStateCacheOpts = {
     /** Keep max n state epochs in memory, persist the rest to disk */
     maxCPStateEpochsInMemory?: number;
-    /** Keep max n state epochs on disk */
+    /**
+     * On-disk retention of persisted checkpoint states. Selects one of two modes:
+     * - `Infinity` (default) -> tiered retention mode
+     * - any finite `n` (>= 0) -> legacy flat retention (keep the last n dense epochs)
+     */
     maxCPStateEpochsOnDisk?: number;
 };
 type PersistentCheckpointStateCacheModules = {
@@ -43,6 +47,7 @@ export declare const DEFAULT_MAX_CP_STATE_EPOCHS_IN_MEMORY = 3;
  * and instead require a resync from last finalized checkpoint state which could be very far in the past.
  */
 export declare const DEFAULT_MAX_CP_STATE_ON_DISK: number;
+export declare const CP_STATE_TIER_BASE = 16;
 /**
  * An implementation of CheckpointStateCache that keep up to n epoch checkpoint states in memory and persist the rest to disk
  * - If it's more than `maxEpochsInMemory` epochs old, it will persist n last epochs to disk based on the view of the block
@@ -88,6 +93,19 @@ export declare class PersistentCheckpointStateCache implements CheckpointStateCa
     private preComputedCheckpointHits;
     private readonly maxEpochsInMemory;
     private readonly maxEpochsOnDisk;
+    /**
+     * Persist checkpoint states (epoch + root) by tiers
+     *
+     *                   ╔═════════ tier 2 ══════════╦═══════ tier 1 ═══════╦═══ tier 0 (dense) ══╗
+     * finalizedEpoch -> ║  keep 1 epoch per 256     ║  keep 1 epoch per 16 ║  keep every epoch   ║ -> head
+     *                   ║  x·······x·······x······  ║  x···x···x···x···    ║  xxxxxxxxxxxxxxxxx  ║
+     *                   ╚═══════════════════════════╩══════════════════════╩═════════════════════╝
+     *
+     * starting from tier 1, all epochs must be aligned to the finalized epoch
+     */
+    private persistentTiers;
+    private finalizedEpoch;
+    private justifiedEpoch;
     private readonly datastore;
     private readonly blockStateCache;
     private readonly bufferPool?;
@@ -138,9 +156,31 @@ export declare class PersistentCheckpointStateCache implements CheckpointStateCa
      */
     updatePreComputedCheckpoint(rootHex: RootHex, epoch: Epoch): number | null;
     /**
-     * This is just to conform to the old implementation
+     * This is called on every checkpoint event to refresh the pinned finalized/justified epochs.
+     */
+    onCheckpoint(finalizedEpoch: Epoch, justifiedEpoch: Epoch): void;
+    /**
+     * This is called right after we persist a checkpoint state.
+     */
+    private onPersist;
+    /**
+     * When tier `n` overflows (> CP_STATE_TIER_BASE epochs), evict its oldest epoch and either promote it to tier `n + 1` (if aligned there) or delete it.
+     *
+     *   before:  persistentTiers[n]   = { ..., e_old }
+     *            persistentTiers[n+1] = { ... }
+     *
+     *   after, if e_old aligns to n+1:           |  after, if e_old does NOT align to n+1:
+     *     persistentTiers[n]   = { ... }         |    persistentTiers[n]   = { ... }
+     *     persistentTiers[n+1] = { ..., e_old }  |    e_old and all its roots deleted from disk
+     *
+     * Since pruning a tier[n] may push an item at tier[n+1], we must call the function recursively.
+     */
+    private prunePersistentTier;
+    /**
+     * Starting from tier[1], it must be aligned to the finalized epoch
+     * ie given finalized epoch F, tier[n] only epochs of F + n*16, n = 1,2,3...
      */
-    prune(): void;
+    private alignedForTier;
     /**
      * Prune all checkpoint states before the provided finalized epoch.
      * Driven sequentially from processState() so it never interleaves with persist.
@@ -215,7 +255,7 @@ export declare class PersistentCheckpointStateCache implements CheckpointStateCa
      * Use seed state from the block cache if cannot find any seed states within this cache.
      */
     findSeedStateToReload(reloadedCp: CheckpointHex): IBeaconStateView;
-    clear(): void;
+    clear(): Promise<void>;
     /** ONLY FOR DEBUGGING PURPOSES. For lodestar debug API */
     dumpSummary(): routes.lodestar.StateCacheItem[];
     getStates(): IterableIterator<IBeaconStateView>;
@@ -264,7 +304,7 @@ export declare class PersistentCheckpointStateCache implements CheckpointStateCa
      */
     private deleteAllEpochItems;
     /**
-     * Prune persisted checkpoint states from disk.
+     * Legacy flat-window on-disk pruning, used only when a `maxEpochsOnDisk` is configured.
      * Note that this should handle all possible errors and not throw.
      */
     private prunePersistedStates;
@@ -275,6 +315,8 @@ export declare class PersistentCheckpointStateCache implements CheckpointStateCa
      * This is 2x - 3x faster than allocating memory every time.
      */
     private serializeStateValidators;
+    /** Tiered pruning is active with the default `Infinity` on-disk cap; a finite cap uses the flat path */
+    private get isTieredMode();
 }
 export declare function toCheckpointHex(checkpoint: phase0.Checkpoint): CheckpointHex;
 export declare function toCheckpointKey(cp: CheckpointHex): string;

package/lib/chain/stateCache/persistentCheckpointsCache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"persistentCheckpointsCache.d.ts","sourceRoot":"","sources":["../../../src/chain/stateCache/persistentCheckpointsCache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"persistentCheckpointsCache.d.ts","sourceRoot":"","sources":["../../../src/chain/stateCache/persistentCheckpointsCache.ts"],"names":[],"mappings":"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"}

package/lib/chain/stateCache/persistentCheckpointsCache.js

@@ -69,6 +69,17 @@ export const DEFAULT_MAX_CP_STATE_EPOCHS_IN_MEMORY = 3;
  * and instead require a resync from last finalized checkpoint state which could be very far in the past.
  */
 export const DEFAULT_MAX_CP_STATE_ON_DISK = Infinity;
+// CP_STATE_TIER_BASE = spacing multiplier per tier AND per-tier capacity. Deciding capacity == base
+// so that a full tier[n] always holds exactly ONE epoch aligned to tier[n+1]
+// given tier[n] has span = 16 ^ n and tier[n+1] has span = 16 ^ (n+1)
+// why 16?
+//   - tier 0 is the dense hot-regen window; it must exceed regen's MAX_EPOCH_TO_PROCESS (=5).
+//   - with a full 4 tiers = 64 epochs, we can cover ~ a year of continuous non-finality, and it'll grow very slowly after that
+//     - tier0 spans 16 epochs ≈ 1.7h, this is more than enough to handle reorg
+//     - tier1 spans 256 epochs ≈ 1.1d, ie we store 16 epochs of the previous day
+//     - tier2 spans 4096 epochs ≈ 18d, ie we store 16 epochs of the last ~2.5 weeks
+//     - tier3 spans 65536ep ≈ 291d, ie we store 16 epochs of the last 0.8 year
+export const CP_STATE_TIER_BASE = 16;
 // TODO GLOAS: re-evaluate this timing
 const PROCESS_CHECKPOINT_STATES_BPS = 6667;
 /**
@@ -116,6 +127,19 @@ export class PersistentCheckpointStateCache {
     preComputedCheckpointHits = null;
     maxEpochsInMemory;
     maxEpochsOnDisk;
+    /**
+     * Persist checkpoint states (epoch + root) by tiers
+     *
+     *                   ╔═════════ tier 2 ══════════╦═══════ tier 1 ═══════╦═══ tier 0 (dense) ══╗
+     * finalizedEpoch -> ║  keep 1 epoch per 256     ║  keep 1 epoch per 16 ║  keep every epoch   ║ -> head
+     *                   ║  x·······x·······x······  ║  x···x···x···x···    ║  xxxxxxxxxxxxxxxxx  ║
+     *                   ╚═══════════════════════════╩══════════════════════╩═════════════════════╝
+     *
+     * starting from tier 1, all epochs must be aligned to the finalized epoch
+     */
+    persistentTiers = [new Map()];
+    finalizedEpoch = 0;
+    justifiedEpoch = 0;
     datastore;
     blockStateCache;
     bufferPool;
@@ -144,6 +168,13 @@ export class PersistentCheckpointStateCache {
                 metrics.cpStateCache.size.set({ type: CacheItemType.inMemory }, inMemoryCount);
                 metrics.cpStateCache.epochSize.set({ type: CacheItemType.persisted }, persistentEpochs.size);
                 metrics.cpStateCache.epochSize.set({ type: CacheItemType.inMemory }, memoryEpochs.size);
+                for (let tier = 0; tier < this.persistentTiers.length; tier++) {
+                    let states = 0;
+                    for (const roots of this.persistentTiers[tier].values())
+                        states += roots.size;
+                    metrics.cpStateCache.persistentTierEpochs.set({ tier }, this.persistentTiers[tier].size);
+                    metrics.cpStateCache.persistentTierStates.set({ tier }, states);
+                }
             });
         }
         this.logger = logger;
@@ -386,10 +417,74 @@ export class PersistentCheckpointStateCache {
         return previousHits;
     }
     /**
-     * This is just to conform to the old implementation
+     * This is called on every checkpoint event to refresh the pinned finalized/justified epochs.
+     */
+    onCheckpoint(finalizedEpoch, justifiedEpoch) {
+        this.finalizedEpoch = finalizedEpoch;
+        this.justifiedEpoch = justifiedEpoch;
+    }
+    /**
+     * This is called right after we persist a checkpoint state.
+     */
+    async onPersist(epoch, rootHex) {
+        let roots = this.persistentTiers[0].get(epoch);
+        if (roots === undefined) {
+            roots = new Set();
+            this.persistentTiers[0].set(epoch, roots);
+        }
+        roots.add(rootHex);
+        await this.prunePersistentTier(0);
+    }
+    /**
+     * When tier `n` overflows (> CP_STATE_TIER_BASE epochs), evict its oldest epoch and either promote it to tier `n + 1` (if aligned there) or delete it.
+     *
+     *   before:  persistentTiers[n]   = { ..., e_old }
+     *            persistentTiers[n+1] = { ... }
+     *
+     *   after, if e_old aligns to n+1:           |  after, if e_old does NOT align to n+1:
+     *     persistentTiers[n]   = { ... }         |    persistentTiers[n]   = { ... }
+     *     persistentTiers[n+1] = { ..., e_old }  |    e_old and all its roots deleted from disk
+     *
+     * Since pruning a tier[n] may push an item at tier[n+1], we must call the function recursively.
+     */
+    async prunePersistentTier(tier) {
+        const tierMap = this.persistentTiers[tier];
+        while (tierMap.size > CP_STATE_TIER_BASE) {
+            // Evict the oldest epoch, but never the pinned justified epoch
+            const oldestEpoch = Math.min(...Array.from(tierMap.keys()).filter((epoch) => epoch !== this.justifiedEpoch));
+            const roots = tierMap.get(oldestEpoch);
+            tierMap.delete(oldestEpoch);
+            const rootHexes = Array.from(roots).join(",");
+            // `>= finalizedEpoch` guards the transient window where an epoch below the (fork-choice)
+            // finalized epoch has not yet been removed by pruneFinalized: its offset would be negative
+            // and JS `%` could spuriously report it as aligned. Such epochs are stale -> delete.
+            if (oldestEpoch >= this.finalizedEpoch && this.alignedForTier(oldestEpoch, tier + 1)) {
+                if (this.persistentTiers[tier + 1] === undefined) {
+                    this.persistentTiers[tier + 1] = new Map();
+                }
+                this.persistentTiers[tier + 1].set(oldestEpoch, roots);
+                this.logger.verbose("Migrated persistent checkpoint states to lower tier", {
+                    epoch: oldestEpoch,
+                    fromTier: tier,
+                    toTier: tier + 1,
+                    rootHexes,
+                });
+                await this.prunePersistentTier(tier + 1);
+            }
+            else {
+                // the oldest epoch is not aligned to the next tier
+                await this.deleteAllEpochItems(oldestEpoch)
+                    .then(() => this.logger.verbose("Pruned checkpoint states from disk", { epoch: oldestEpoch, tier, rootHexes }))
+                    .catch((e) => this.logger.debug("Error delete all epoch items", { epoch: oldestEpoch, tier }, e));
+            }
+        }
+    }
+    /**
+     * Starting from tier[1], it must be aligned to the finalized epoch
+     * ie given finalized epoch F, tier[n] only epochs of F + n*16, n = 1,2,3...
      */
-    prune() {
-        // do nothing
+    alignedForTier(epoch, tier) {
+        return (epoch - this.finalizedEpoch) % CP_STATE_TIER_BASE ** tier === 0;
     }
     /**
      * Prune all checkpoint states before the provided finalized epoch.
@@ -559,9 +654,10 @@ export class PersistentCheckpointStateCache {
         this.logger.verbose("Reload: use default block state as seed state", { stateSlot: seedBlockState.slot, ...logCtx });
         return seedBlockState;
     }
-    clear() {
-        this.cache.clear();
-        this.epochIndex.clear();
+    async clear() {
+        // deleteAllEpochItems removes every root of an epoch from disk and clears the cache
+        await Promise.all(Array.from(this.epochIndex.keys()).map((epoch) => this.deleteAllEpochItems(epoch).catch((e) => this.logger.debug("Error delete all epoch items on clear", { epoch }, e))));
+        this.persistentTiers = [new Map()];
     }
     /** ONLY FOR DEBUGGING PURPOSES. For lodestar debug API */
     dumpSummary() {
@@ -685,6 +781,9 @@ export class PersistentCheckpointStateCache {
                     }
                     // overwrite cpKey, this means the state is deleted from memory
                     this.cache.set(cpKey, { type: CacheItemType.persisted, value: persistedKey });
+                    if (this.isTieredMode) {
+                        await this.onPersist(epoch, rootHex);
+                    }
                 }
                 else {
                     if (persistedKey) {
@@ -692,6 +791,9 @@ export class PersistentCheckpointStateCache {
                         // this also means the state is deleted from memory
                         this.cache.set(cpKey, { type: CacheItemType.persisted, value: persistedKey });
                         // do not update epochIndex
+                        if (this.isTieredMode) {
+                            await this.onPersist(epoch, rootHex);
+                        }
                     }
                     else {
                         // delete the state from memory
@@ -731,6 +833,10 @@ export class PersistentCheckpointStateCache {
             this.cache.delete(key);
         }
         this.epochIndex.delete(epoch);
+        // keep the on-disk retention tiers in sync so they never drift from epochIndex
+        for (const tierMap of this.persistentTiers) {
+            tierMap.delete(epoch);
+        }
         this.logger.verbose("Pruned checkpoint states for epoch", {
             epoch,
             persistCount,
@@ -738,7 +844,7 @@ export class PersistentCheckpointStateCache {
         });
     }
     /**
-     * Prune persisted checkpoint states from disk.
+     * Legacy flat-window on-disk pruning, used only when a `maxEpochsOnDisk` is configured.
      * Note that this should handle all possible errors and not throw.
      */
     prunePersistedStates() {
@@ -773,6 +879,10 @@ export class PersistentCheckpointStateCache {
         }
         return null;
     }
+    /** Tiered pruning is active with the default `Infinity` on-disk cap; a finite cap uses the flat path */
+    get isTieredMode() {
+        return this.maxEpochsOnDisk === Infinity;
+    }
 }
 export function toCheckpointHex(checkpoint) {
     return {