@lodestar/beacon-node 1.35.0-dev.e18102ed8c → 1.35.0-dev.f45a2be721

package/src/chain/stateCache/fifoBlockStateCache.ts

@@ -0,0 +1,208 @@
+import {routes} from "@lodestar/api";
+import {CachedBeaconStateAllForks} from "@lodestar/state-transition";
+import {RootHex} from "@lodestar/types";
+import {toRootHex} from "@lodestar/utils";
+import {Metrics} from "../../metrics/index.js";
+import {LinkedList} from "../../util/array.js";
+import {StateRegenerationOpts} from "../regen/interface.js";
+import {MapTracker} from "./mapMetrics.js";
+import {BlockStateCache} from "./types.js";
+
+export type FIFOBlockStateCacheOpts = {
+  maxBlockStates?: number;
+};
+
+/**
+ * Given `maxSkipSlots` = 32 and `DEFAULT_EARLIEST_PERMISSIBLE_SLOT_DISTANCE` = 32, lodestar doesn't need to
+ * reload states in order to process a gossip block.
+ *
+ * |-----------------------------------------------|-----------------------------------------------|
+ *                 maxSkipSlots                      DEFAULT_EARLIEST_PERMISSIBLE_SLOT_DISTANCE    ^
+ *                                                                                             clock slot
+ */
+export const DEFAULT_MAX_BLOCK_STATES = 64;
+
+/**
+ * New implementation of BlockStateCache that keeps the most recent n states consistently
+ *  - Maintain a linked list (FIFO) with special handling for head state, which is always the first item in the list
+ *  - Prune per add() instead of per checkpoint so it only keeps n historical states consistently, prune from tail
+ *  - No need to prune per finalized checkpoint
+ *
+ * Given this block tree with Block 11 as head:
+ * ```
+         Block 10
+           |
+     +-----+-----+
+     |           |
+  Block 11   Block 12
+     ^           |
+     |           |
+    head       Block 13
+ * ```
+ * The maintained key order would be: 11 -> 13 -> 12 -> 10, and state 10 will be pruned first.
+ */
+export class FIFOBlockStateCache implements BlockStateCache {
+  /**
+   * Max number of states allowed in the cache
+   */
+  readonly maxStates: number;
+
+  private readonly cache: MapTracker<string, CachedBeaconStateAllForks>;
+  /**
+   * Key order to implement FIFO cache
+   */
+  private readonly keyOrder: LinkedList<string>;
+  private readonly metrics: Metrics["stateCache"] | null | undefined;
+
+  constructor(opts: FIFOBlockStateCacheOpts, {metrics}: {metrics?: Metrics | null}) {
+    this.maxStates = opts.maxBlockStates ?? DEFAULT_MAX_BLOCK_STATES;
+    this.cache = new MapTracker(metrics?.stateCache);
+    if (metrics) {
+      this.metrics = metrics.stateCache;
+      metrics.stateCache.size.addCollect(() => metrics.stateCache.size.set(this.cache.size));
+    }
+    this.keyOrder = new LinkedList();
+  }
+
+  /**
+   * Set a state as head, happens when importing a block and head block is changed.
+   */
+  setHeadState(item: CachedBeaconStateAllForks | null): void {
+    if (item !== null) {
+      this.add(item, true);
+    }
+  }
+
+  /**
+   * Get a seed state for state reload, this could be any states. The goal is to have the same
+   * base merkle tree for all BeaconState objects across application.
+   * See packages/state-transition/src/util/loadState/loadState.ts for more detail
+   */
+  getSeedState(): CachedBeaconStateAllForks {
+    const firstValue = this.cache.values().next();
+    if (firstValue.done) {
+      // should not happen
+      throw Error("No state in FIFOBlockStateCache");
+    }
+
+    const firstState = firstValue.value;
+    // don't transfer cache because consumer only use this cache to reload another state from disc
+    return firstState.clone(true);
+  }
+
+  /**
+   * Get a state from this cache given a state root hex.
+   */
+  get(rootHex: RootHex, opts?: StateRegenerationOpts): CachedBeaconStateAllForks | null {
+    this.metrics?.lookups.inc();
+    const item = this.cache.get(rootHex);
+    if (!item) {
+      return null;
+    }
+
+    this.metrics?.hits.inc();
+    this.metrics?.stateClonedCount.observe(item.clonedCount);
+
+    return item.clone(opts?.dontTransferCache);
+  }
+
+  /**
+   * Add a state to this cache.
+   * @param isHead if true, move it to the head of the list. Otherwise add to the 2nd position.
+   * In importBlock() steps, normally it'll call add() with isHead = false first. Then call setHeadState() to set the head.
+   */
+  add(item: CachedBeaconStateAllForks, isHead = false): void {
+    const key = toRootHex(item.hashTreeRoot());
+    if (this.cache.get(key) != null) {
+      if (!this.keyOrder.has(key)) {
+        throw Error(`State exists but key not found in keyOrder: ${key}`);
+      }
+      if (isHead) {
+        this.keyOrder.moveToHead(key);
+      } else {
+        this.keyOrder.moveToSecond(key);
+      }
+      // same size, no prune
+      return;
+    }
+
+    // new state
+    this.metrics?.adds.inc();
+    this.cache.set(key, item);
+    if (isHead) {
+      this.keyOrder.unshift(key);
+    } else {
+      // insert after head
+      const head = this.keyOrder.first();
+      if (head == null) {
+        // should not happen, however handle just in case
+        this.keyOrder.unshift(key);
+      } else {
+        this.keyOrder.insertAfter(head, key);
+      }
+    }
+    this.prune(key);
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+
+  /**
+   * 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 {
+    while (this.keyOrder.length > this.maxStates) {
+      const key = this.keyOrder.last();
+      // it does not make sense to prune the last added state
+      // this only happens when max state is 1 in a short period of time
+      if (key === lastAddedKey) {
+        break;
+      }
+      if (!key) {
+        // should not happen
+        throw new Error("No key");
+      }
+      this.keyOrder.pop();
+      this.cache.delete(key);
+    }
+  }
+
+  /**
+   * No need for this implementation
+   * This is only to conform to the old api
+   */
+  deleteAllBeforeEpoch(): void {}
+
+  /**
+   * ONLY FOR DEBUGGING PURPOSES. For lodestar debug API.
+   */
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /** ONLY FOR DEBUGGING PURPOSES. For lodestar debug API */
+  dumpSummary(): routes.lodestar.StateCacheItem[] {
+    return Array.from(this.cache.entries()).map(([key, state]) => ({
+      slot: state.slot,
+      root: toRootHex(state.hashTreeRoot()),
+      reads: this.cache.readCount.get(key) ?? 0,
+      lastRead: this.cache.lastRead.get(key) ?? 0,
+      checkpointState: false,
+    }));
+  }
+
+  getStates(): IterableIterator<CachedBeaconStateAllForks> {
+    return this.cache.values();
+  }
+
+  /**
+   * For unit test only.
+   */
+  dumpKeyOrder(): string[] {
+    return this.keyOrder.toArray();
+  }
+}

package/src/chain/stateCache/inMemoryCheckpointsCache.ts

@@ -0,0 +1,198 @@
+import {routes} from "@lodestar/api";
+import {CachedBeaconStateAllForks} from "@lodestar/state-transition";
+import {Epoch, RootHex, phase0} from "@lodestar/types";
+import {MapDef, toRootHex} from "@lodestar/utils";
+import {Metrics} from "../../metrics/index.js";
+import {StateRegenerationOpts} from "../regen/interface.js";
+import {MapTracker} from "./mapMetrics.js";
+import {CacheItemType, CheckpointStateCache} from "./types.js";
+
+export type CheckpointHex = {epoch: Epoch; rootHex: RootHex};
+const MAX_EPOCHS = 10;
+
+/**
+ * In memory cache of CachedBeaconState
+ * belonging to checkpoint
+ *
+ * Similar API to Repository
+ */
+export class InMemoryCheckpointStateCache implements CheckpointStateCache {
+  private readonly cache: MapTracker<string, CachedBeaconStateAllForks>;
+  /** Epoch -> Set<blockRoot> */
+  private readonly epochIndex = new MapDef<Epoch, Set<string>>(() => new Set<string>());
+  /**
+   * Max number of epochs allowed in the cache
+   */
+  private readonly maxEpochs: number;
+  private readonly metrics: Metrics["cpStateCache"] | null | undefined;
+  private preComputedCheckpoint: string | null = null;
+  private preComputedCheckpointHits: number | null = null;
+
+  constructor({metrics = null}: {metrics?: Metrics | null}, {maxEpochs = MAX_EPOCHS}: {maxEpochs?: number} = {}) {
+    this.cache = new MapTracker(metrics?.cpStateCache);
+    if (metrics) {
+      this.metrics = metrics.cpStateCache;
+      metrics.cpStateCache.size.addCollect(() =>
+        metrics.cpStateCache.size.set({type: CacheItemType.inMemory}, this.cache.size)
+      );
+      metrics.cpStateCache.epochSize.addCollect(() =>
+        metrics.cpStateCache.epochSize.set({type: CacheItemType.inMemory}, this.epochIndex.size)
+      );
+    }
+    this.maxEpochs = maxEpochs;
+  }
+
+  async getOrReload(cp: CheckpointHex, opts?: StateRegenerationOpts): Promise<CachedBeaconStateAllForks | null> {
+    return this.get(cp, opts);
+  }
+
+  async getStateOrBytes(cp: CheckpointHex): Promise<Uint8Array | CachedBeaconStateAllForks | null> {
+    // no need to transfer cache for this api
+    return this.get(cp, {dontTransferCache: true});
+  }
+
+  async getOrReloadLatest(
+    rootHex: string,
+    maxEpoch: number,
+    opts?: StateRegenerationOpts
+  ): Promise<CachedBeaconStateAllForks | null> {
+    return this.getLatest(rootHex, maxEpoch, opts);
+  }
+
+  async processState(): Promise<number> {
+    // do nothing, this class does not support prunning
+    return 0;
+  }
+
+  get(cp: CheckpointHex, opts?: StateRegenerationOpts): CachedBeaconStateAllForks | null {
+    this.metrics?.lookups.inc();
+    const cpKey = toCheckpointKey(cp);
+    const item = this.cache.get(cpKey);
+
+    if (!item) {
+      return null;
+    }
+
+    this.metrics?.hits.inc();
+
+    if (cpKey === this.preComputedCheckpoint) {
+      this.preComputedCheckpointHits = (this.preComputedCheckpointHits ?? 0) + 1;
+    }
+
+    this.metrics?.stateClonedCount.observe(item.clonedCount);
+
+    return item.clone(opts?.dontTransferCache);
+  }
+
+  add(cp: phase0.Checkpoint, item: CachedBeaconStateAllForks): void {
+    const cpHex = toCheckpointHex(cp);
+    const key = toCheckpointKey(cpHex);
+    if (this.cache.has(key)) {
+      return;
+    }
+    this.metrics?.adds.inc();
+    this.cache.set(key, item);
+    this.epochIndex.getOrDefault(cp.epoch).add(cpHex.rootHex);
+  }
+
+  /**
+   * Searches for the latest cached state with a `root`, starting with `epoch` and descending
+   */
+  getLatest(rootHex: RootHex, maxEpoch: Epoch, opts?: StateRegenerationOpts): CachedBeaconStateAllForks | null {
+    // sort epochs in descending order, only consider epochs lte `epoch`
+    const epochs = Array.from(this.epochIndex.keys())
+      .sort((a, b) => b - a)
+      .filter((e) => e <= maxEpoch);
+    for (const epoch of epochs) {
+      if (this.epochIndex.get(epoch)?.has(rootHex)) {
+        return this.get({rootHex, epoch}, opts);
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Update the precomputed checkpoint and return the number of his for the
+   * previous one (if any).
+   */
+  updatePreComputedCheckpoint(rootHex: RootHex, epoch: Epoch): number | null {
+    const previousHits = this.preComputedCheckpointHits;
+    this.preComputedCheckpoint = toCheckpointKey({rootHex, epoch});
+    this.preComputedCheckpointHits = 0;
+    return previousHits;
+  }
+
+  pruneFinalized(finalizedEpoch: Epoch): void {
+    for (const epoch of this.epochIndex.keys()) {
+      if (epoch < finalizedEpoch) {
+        this.deleteAllEpochItems(epoch);
+      }
+    }
+  }
+
+  prune(finalizedEpoch: Epoch, justifiedEpoch: Epoch): void {
+    const epochs = Array.from(this.epochIndex.keys()).filter(
+      (epoch) => epoch !== finalizedEpoch && epoch !== justifiedEpoch
+    );
+    if (epochs.length > this.maxEpochs) {
+      for (const epoch of epochs.slice(0, epochs.length - this.maxEpochs)) {
+        this.deleteAllEpochItems(epoch);
+      }
+    }
+  }
+
+  delete(cp: phase0.Checkpoint): void {
+    this.cache.delete(toCheckpointKey(toCheckpointHex(cp)));
+    const epochKey = toRootHex(cp.root);
+    const value = this.epochIndex.get(cp.epoch);
+    if (value) {
+      value.delete(epochKey);
+      if (value.size === 0) {
+        this.epochIndex.delete(cp.epoch);
+      }
+    }
+  }
+
+  deleteAllEpochItems(epoch: Epoch): void {
+    for (const rootHex of this.epochIndex.get(epoch) || []) {
+      this.cache.delete(toCheckpointKey({rootHex, epoch}));
+    }
+    this.epochIndex.delete(epoch);
+  }
+
+  clear(): void {
+    this.cache.clear();
+    this.epochIndex.clear();
+  }
+
+  /** ONLY FOR DEBUGGING PURPOSES. For lodestar debug API */
+  dumpSummary(): routes.lodestar.StateCacheItem[] {
+    return Array.from(this.cache.entries()).map(([key, state]) => ({
+      slot: state.slot,
+      root: toRootHex(state.hashTreeRoot()),
+      reads: this.cache.readCount.get(key) ?? 0,
+      lastRead: this.cache.lastRead.get(key) ?? 0,
+      checkpointState: true,
+    }));
+  }
+
+  getStates(): IterableIterator<CachedBeaconStateAllForks> {
+    return this.cache.values();
+  }
+
+  /** ONLY FOR DEBUGGING PURPOSES. For spec tests on error */
+  dumpCheckpointKeys(): string[] {
+    return Array.from(this.cache.keys());
+  }
+}
+
+export function toCheckpointHex(checkpoint: phase0.Checkpoint): CheckpointHex {
+  return {
+    epoch: checkpoint.epoch,
+    rootHex: toRootHex(checkpoint.root),
+  };
+}
+
+export function toCheckpointKey(cp: CheckpointHex): string {
+  return `${cp.rootHex}:${cp.epoch}`;
+}

package/src/chain/stateCache/index.ts

@@ -0,0 +1,3 @@
+export * from "./blockStateCacheImpl.js";
+export * from "./fifoBlockStateCache.js";
+export * from "./inMemoryCheckpointsCache.js";

package/src/chain/stateCache/mapMetrics.ts

@@ -0,0 +1,52 @@
+import {AvgMinMax} from "@lodestar/utils";
+
+type MapTrackerMetrics = {
+  reads: AvgMinMax;
+  secondsSinceLastRead: AvgMinMax;
+};
+
+export class MapTracker<K, V> extends Map<K, V> {
+  /** Tracks the number of reads each entry in the cache gets for metrics */
+  readonly readCount = new Map<K, number>();
+  /** Tracks the last time a state was read from the cache */
+  readonly lastRead = new Map<K, number>();
+
+  constructor(metrics?: MapTrackerMetrics) {
+    super();
+    if (metrics) {
+      metrics.reads.addGetValuesFn(() => Array.from(this.readCount.values()));
+      metrics.secondsSinceLastRead.addGetValuesFn(() => {
+        const now = Date.now();
+        const secondsSinceLastRead: number[] = [];
+        for (const lastRead of this.lastRead.values()) {
+          secondsSinceLastRead.push((now - lastRead) / 1000);
+        }
+        return secondsSinceLastRead;
+      });
+    }
+  }
+
+  get(key: K): V | undefined {
+    const value = super.get(key);
+    if (value !== undefined) {
+      this.readCount.set(key, 1 + (this.readCount.get(key) ?? 0));
+      this.lastRead.set(key, Date.now());
+    }
+    return value;
+  }
+
+  delete(key: K): boolean {
+    const deleted = super.delete(key);
+    if (deleted) {
+      this.readCount.delete(key);
+      this.lastRead.delete(key);
+    }
+    return deleted;
+  }
+
+  clear(): void {
+    super.clear();
+    this.readCount.clear();
+    this.lastRead.clear();
+  }
+}