@feelyourprotocol/statemanager 8141.0.0

package/src/cache/account.ts

@@ -0,0 +1,277 @@
+import { bytesToUnprefixedHex } from '@feelyourprotocol/util'
+import { OrderedMap } from '@js-sdsl/ordered-map'
+import debugDefault from 'debug'
+import { LRUCache } from 'lru-cache'
+
+import { Cache } from './cache.ts'
+import { CacheType } from './types.ts'
+
+import type { Account, Address } from '@feelyourprotocol/util'
+import type { CacheOpts } from './types.ts'
+
+/**
+ * account: undefined
+ *
+ * Account is known to not exist in the trie
+ */
+type AccountCacheElement = {
+  accountRLP: Uint8Array | undefined
+}
+
+export class AccountCache extends Cache {
+  _lruCache: LRUCache<string, AccountCacheElement> | undefined
+  _orderedMapCache: OrderedMap<string, AccountCacheElement> | undefined
+
+  /**
+   * Diff cache collecting the state of the cache
+   * at the beginning of checkpoint height
+   * (respectively: before a first modification)
+   *
+   * If the whole cache element is undefined (in contrast
+   * to the account), the element didn't exist in the cache
+   * before.
+   */
+  _diffCache: Map<string, AccountCacheElement | undefined>[] = []
+  constructor(opts: CacheOpts) {
+    super()
+    if (opts.type === CacheType.LRU) {
+      this._lruCache = new LRUCache({
+        max: opts.size,
+        updateAgeOnGet: true,
+      })
+    } else {
+      this._orderedMapCache = new OrderedMap()
+    }
+
+    this._diffCache.push(new Map<string, AccountCacheElement | undefined>())
+    this._debug = debugDefault('statemanager:cache:account')
+  }
+
+  _saveCachePreState(cacheKeyHex: string) {
+    const diffMap = this._diffCache[this._checkpoints]
+    if (!diffMap.has(cacheKeyHex)) {
+      let oldElem: AccountCacheElement | undefined
+      if (this._lruCache) {
+        oldElem = this._lruCache!.get(cacheKeyHex)
+      } else {
+        oldElem = this._orderedMapCache!.getElementByKey(cacheKeyHex)
+      }
+      diffMap.set(cacheKeyHex, oldElem)
+    }
+  }
+
+  /**
+   * Puts account to cache under its address.
+   * @param address - Address of account
+   * @param account - Account or undefined if account doesn't exist in the trie
+   */
+  put(
+    address: Address,
+    account: Account | undefined,
+    couldBePartialAccount: boolean = false,
+  ): void {
+    // Using deprecated bytesToUnprefixedHex for performance: used as Map keys for cache lookups.
+    const addressHex = bytesToUnprefixedHex(address.bytes)
+    this._saveCachePreState(addressHex)
+    const elem = {
+      accountRLP:
+        account !== undefined
+          ? couldBePartialAccount
+            ? account.serializeWithPartialInfo()
+            : account.serialize()
+          : undefined,
+    }
+
+    if (this.DEBUG) {
+      this._debug(`Put account ${addressHex}`)
+    }
+    if (this._lruCache) {
+      this._lruCache!.set(addressHex, elem)
+    } else {
+      this._orderedMapCache!.setElement(addressHex, elem)
+    }
+    this._stats.writes += 1
+  }
+
+  /**
+   * Returns the queried account or undefined if account doesn't exist
+   * @param address - Address of account
+   */
+  get(address: Address): AccountCacheElement | undefined {
+    // Using deprecated bytesToUnprefixedHex for performance: used as Map keys for cache lookups.
+    const addressHex = bytesToUnprefixedHex(address.bytes)
+    if (this.DEBUG) {
+      this._debug(`Get account ${addressHex}`)
+    }
+
+    let elem: AccountCacheElement | undefined
+    if (this._lruCache) {
+      elem = this._lruCache!.get(addressHex)
+    } else {
+      elem = this._orderedMapCache!.getElementByKey(addressHex)
+    }
+    this._stats.reads += 1
+    if (elem) {
+      this._stats.hits += 1
+    }
+    return elem
+  }
+
+  /**
+   * Marks address as deleted in cache.
+   * @param address - Address
+   */
+  del(address: Address): void {
+    // Using deprecated bytesToUnprefixedHex for performance: used as Map keys for cache lookups.
+    const addressHex = bytesToUnprefixedHex(address.bytes)
+    this._saveCachePreState(addressHex)
+    if (this.DEBUG) {
+      this._debug(`Delete account ${addressHex}`)
+    }
+    if (this._lruCache) {
+      this._lruCache!.set(addressHex, {
+        accountRLP: undefined,
+      })
+    } else {
+      this._orderedMapCache!.setElement(addressHex, {
+        accountRLP: undefined,
+      })
+    }
+
+    this._stats.deletions += 1
+  }
+
+  /**
+   * Flushes cache by returning accounts that have been modified
+   * or deleted and resetting the diff cache (at checkpoint height).
+   */
+  flush(): [string, AccountCacheElement][] {
+    if (this.DEBUG) {
+      this._debug(`Flushing cache on checkpoint ${this._checkpoints}`)
+    }
+
+    const diffMap = this._diffCache[this._checkpoints]!
+
+    const items: [string, AccountCacheElement][] = []
+
+    for (const entry of diffMap.entries()) {
+      const cacheKeyHex = entry[0]
+      let elem: AccountCacheElement | undefined
+      if (this._lruCache) {
+        elem = this._lruCache!.get(cacheKeyHex)
+      } else {
+        elem = this._orderedMapCache!.getElementByKey(cacheKeyHex)
+      }
+
+      if (elem !== undefined) {
+        items.push([cacheKeyHex, elem])
+      }
+    }
+    this._diffCache[this._checkpoints] = new Map<string, AccountCacheElement | undefined>()
+    return items
+  }
+
+  /**
+   * Revert changes to cache last checkpoint (no effect on trie).
+   */
+  revert(): void {
+    this._checkpoints -= 1
+    if (this.DEBUG) {
+      this._debug(`Revert to checkpoint ${this._checkpoints}`)
+    }
+    const diffMap = this._diffCache.pop()!
+    for (const entry of diffMap.entries()) {
+      const addressHex = entry[0]
+      const elem = entry[1]
+      if (elem === undefined) {
+        if (this._lruCache) {
+          this._lruCache!.delete(addressHex)
+        } else {
+          this._orderedMapCache!.eraseElementByKey(addressHex)
+        }
+      } else {
+        if (this._lruCache) {
+          this._lruCache!.set(addressHex, elem)
+        } else {
+          this._orderedMapCache!.setElement(addressHex, elem)
+        }
+      }
+    }
+  }
+
+  /**
+   * Commits to current state of cache (no effect on trie).
+   */
+  commit(): void {
+    this._checkpoints -= 1
+    if (this.DEBUG) {
+      this._debug(`Commit to checkpoint ${this._checkpoints}`)
+    }
+    const diffMap = this._diffCache.pop()!
+    for (const entry of diffMap.entries()) {
+      const addressHex = entry[0]
+      const oldEntry = this._diffCache[this._checkpoints].has(addressHex)
+      if (!oldEntry) {
+        const elem = entry[1]
+        this._diffCache[this._checkpoints].set(addressHex, elem)
+      }
+    }
+  }
+
+  /**
+   * Marks current state of cache as checkpoint, which can
+   * later on be reverted or committed.
+   */
+  checkpoint(): void {
+    this._checkpoints += 1
+    if (this.DEBUG) {
+      this._debug(`New checkpoint ${this._checkpoints}`)
+    }
+    this._diffCache.push(new Map<string, AccountCacheElement | undefined>())
+  }
+
+  /**
+   * Returns the size of the cache
+   * @returns
+   */
+  size() {
+    if (this._lruCache) {
+      return this._lruCache!.size
+    } else {
+      return this._orderedMapCache!.size()
+    }
+  }
+
+  /**
+   * Returns a dict with cache stats
+   * @param reset
+   */
+  stats(reset = true) {
+    const stats = { ...this._stats }
+    stats.size = this.size()
+    if (reset) {
+      this._stats = {
+        size: 0,
+        reads: 0,
+        hits: 0,
+        writes: 0,
+        deletions: 0,
+      }
+    }
+    return stats
+  }
+
+  /**
+   * Clears cache.
+   */
+  clear(): void {
+    if (this.DEBUG) {
+      this._debug(`Clear cache`)
+    }
+    if (this._lruCache) {
+      this._lruCache!.clear()
+    } else {
+      this._orderedMapCache!.clear()
+    }
+  }
+}

package/src/cache/cache.ts

@@ -0,0 +1,35 @@
+import { isDebugEnabled } from '@feelyourprotocol/util'
+import debugDefault from 'debug'
+
+import type { Debugger } from 'debug'
+
+export class Cache {
+  _debug: Debugger
+
+  _checkpoints = 0
+
+  _stats = {
+    size: 0,
+    reads: 0,
+    hits: 0,
+    writes: 0,
+    deletions: 0,
+  }
+
+  /**
+   * StateManager cache is run in DEBUG mode (default: false)
+   * Taken from DEBUG environment variable
+   *
+   * Safeguards on debug() calls are added for
+   * performance reasons to avoid string literal evaluation
+   * @hidden
+   */
+  protected readonly DEBUG: boolean = false
+
+  constructor() {
+    // Skip DEBUG calls unless 'ethjs' included in environmental DEBUG variables
+    this.DEBUG = isDebugEnabled('ethjs')
+
+    this._debug = debugDefault('statemanager:cache')
+  }
+}

package/src/cache/caches.ts

@@ -0,0 +1,125 @@
+import { AccountCache } from './account.ts'
+import { CodeCache } from './code.ts'
+import { StorageCache } from './storage.ts'
+import { type CacheOpts, CacheType, type CachesStateManagerOpts } from './types.ts'
+
+import type { Address } from '@feelyourprotocol/util'
+
+export class Caches {
+  account?: AccountCache
+  code?: CodeCache
+  storage?: StorageCache
+
+  settings: Record<'account' | 'code' | 'storage', CacheOpts>
+
+  constructor(opts: CachesStateManagerOpts = {}) {
+    const accountSettings = {
+      type: opts.account?.type ?? CacheType.ORDERED_MAP,
+      size: opts.account?.size ?? 100000,
+    }
+
+    const codeSettings = {
+      type: opts.code?.type ?? CacheType.ORDERED_MAP,
+      size: opts.code?.size ?? 20000,
+    }
+
+    const storageSettings = {
+      type: opts.storage?.type ?? CacheType.ORDERED_MAP,
+      size: opts.storage?.size ?? 20000,
+    }
+
+    this.settings = {
+      account: accountSettings,
+      code: codeSettings,
+      storage: storageSettings,
+    }
+
+    if (this.settings.account.size !== 0) {
+      this.account = new AccountCache({
+        size: this.settings.account.size,
+        type: this.settings.account.type,
+      })
+    }
+
+    if (this.settings.code.size !== 0) {
+      this.code = new CodeCache({
+        size: this.settings.code.size,
+        type: this.settings.code.type,
+      })
+    }
+
+    if (this.settings.storage.size !== 0) {
+      this.storage = new StorageCache({
+        size: this.settings.storage.size,
+        type: this.settings.storage.type,
+      })
+    }
+  }
+
+  checkpoint() {
+    this.account?.checkpoint()
+    this.storage?.checkpoint()
+    this.code?.checkpoint()
+  }
+
+  clear() {
+    this.account?.clear()
+    this.storage?.clear()
+    this.code?.clear()
+  }
+
+  commit() {
+    this.account?.commit()
+    this.storage?.commit()
+    this.code?.commit()
+  }
+
+  deleteAccount(address: Address) {
+    this.code?.del(address)
+    this.account?.del(address)
+    this.storage?.clearStorage(address)
+  }
+
+  shallowCopy(downlevelCaches: boolean) {
+    let cacheOptions: CachesStateManagerOpts | undefined
+
+    // Account cache options
+    if (this.settings.account.size !== 0) {
+      cacheOptions = {
+        account: downlevelCaches
+          ? { size: this.settings.account.size, type: CacheType.ORDERED_MAP }
+          : this.settings.account,
+      }
+    }
+
+    // Storage cache options
+    if (this.settings.storage.size !== 0) {
+      cacheOptions = {
+        ...cacheOptions,
+        storage: downlevelCaches
+          ? { size: this.settings.storage.size, type: CacheType.ORDERED_MAP }
+          : this.settings.storage,
+      }
+    }
+
+    // Code cache options
+    if (this.settings.code.size !== 0) {
+      cacheOptions = {
+        ...cacheOptions,
+        code: downlevelCaches
+          ? { size: this.settings.code.size, type: CacheType.ORDERED_MAP }
+          : this.settings.code,
+      }
+    }
+
+    if (cacheOptions !== undefined) {
+      return new Caches(cacheOptions)
+    } else return undefined
+  }
+
+  revert() {
+    this.account?.revert()
+    this.storage?.revert()
+    this.code?.revert()
+  }
+}

package/src/cache/code.ts

@@ -0,0 +1,277 @@
+import { bytesToUnprefixedHex } from '@feelyourprotocol/util'
+import { OrderedMap } from '@js-sdsl/ordered-map'
+import debugDefault from 'debug'
+import { LRUCache } from 'lru-cache'
+
+import { Cache } from './cache.ts'
+import { CacheType } from './types.ts'
+
+import type { Address } from '@feelyourprotocol/util'
+import type { CacheOpts } from './types.ts'
+
+/**
+ * Represents a cached code element.
+ */
+type CodeCacheElement = {
+  code: Uint8Array | undefined
+}
+
+export class CodeCache extends Cache {
+  _lruCache: LRUCache<string, CodeCacheElement> | undefined
+  _orderedMapCache: OrderedMap<string, CodeCacheElement> | undefined
+
+  /**
+   * Diff cache collecting the state of the cache
+   * at the beginning of checkpoint height
+   * (respectively: before a first modification)
+   *
+   * If the whole cache element is undefined (in contrast
+   * to the code), the element didn't exist in the cache
+   * before.
+   */
+  _diffCache: Map<string, CodeCacheElement | undefined>[] = []
+
+  constructor(opts: CacheOpts) {
+    super()
+    if (opts.type === CacheType.LRU) {
+      this._lruCache = new LRUCache({
+        max: opts.size,
+        updateAgeOnGet: true,
+      })
+    } else {
+      this._orderedMapCache = new OrderedMap()
+    }
+
+    this._diffCache.push(new Map<string, CodeCacheElement | undefined>())
+    this._debug = debugDefault('statemanager:cache:code')
+  }
+
+  /**
+   * Saves the state of the code cache before making changes to it.
+   *
+   * @param cacheKeyHex Account key for which code is being modified.
+   */
+  _saveCachePreState(cacheKeyHex: string) {
+    const diffMap = this._diffCache[this._checkpoints]
+    if (!diffMap.has(cacheKeyHex)) {
+      let oldElem: CodeCacheElement | undefined
+      if (this._lruCache) {
+        oldElem = this._lruCache.get(cacheKeyHex)
+      } else {
+        oldElem = this._orderedMapCache!.getElementByKey(cacheKeyHex)
+      }
+      diffMap.set(cacheKeyHex, oldElem)
+    }
+  }
+
+  /**
+   * Puts code into the cache under its hash.
+   *
+   * @param address - Address of account code is being modified for.
+   * @param code - Bytecode or undefined if code doesn't exist.
+   */
+  put(address: Address, code: Uint8Array | undefined): void {
+    // Using deprecated bytesToUnprefixedHex for performance: used as Map keys for cache lookups.
+    const addressHex = bytesToUnprefixedHex(address.bytes)
+    this._saveCachePreState(addressHex)
+    const elem = {
+      code,
+    }
+
+    if (this.DEBUG) {
+      this._debug(`Put code ${addressHex}`)
+    }
+    if (this._lruCache) {
+      this._lruCache.set(addressHex, elem)
+    } else {
+      this._orderedMapCache!.setElement(addressHex, elem)
+    }
+    this._stats.writes += 1
+  }
+
+  /**
+   * Returns the queried code or undefined if it doesn't exist.
+   *
+   * @param address - Account address for which code is being fetched.
+   */
+  get(address: Address): CodeCacheElement | undefined {
+    // Using deprecated bytesToUnprefixedHex for performance: used as Map keys for cache lookups.
+    const addressHex = bytesToUnprefixedHex(address.bytes)
+    if (this.DEBUG) {
+      this._debug(`Get code ${addressHex}`)
+    }
+
+    let elem: CodeCacheElement | undefined
+    if (this._lruCache) {
+      elem = this._lruCache.get(addressHex)
+    } else {
+      elem = this._orderedMapCache!.getElementByKey(addressHex)
+    }
+    this._stats.reads += 1
+    if (elem) {
+      this._stats.hits += 1
+    }
+    return elem
+  }
+
+  /**
+   * Marks code as deleted in the cache.
+   *
+   * @param address - Account address for which code is being fetched.
+   */
+  del(address: Address): void {
+    // Using deprecated bytesToUnprefixedHex for performance: used as Map keys for cache lookups.
+    const addressHex = bytesToUnprefixedHex(address.bytes)
+    this._saveCachePreState(addressHex)
+    if (this.DEBUG) {
+      this._debug(`Delete code ${addressHex}`)
+    }
+    if (this._lruCache) {
+      this._lruCache.set(addressHex, {
+        code: undefined,
+      })
+    } else {
+      this._orderedMapCache!.setElement(addressHex, {
+        code: undefined,
+      })
+    }
+
+    this._stats.deletions += 1
+  }
+
+  /**
+   * Flushes the cache by returning codes that have been modified
+   * or deleted and resetting the diff cache (at checkpoint height).
+   */
+  flush(): [string, CodeCacheElement][] {
+    if (this.DEBUG) {
+      this._debug(`Flushing cache on checkpoint ${this._checkpoints}`)
+    }
+
+    const diffMap = this._diffCache[this._checkpoints]
+
+    const items: [string, CodeCacheElement][] = []
+
+    for (const entry of diffMap.entries()) {
+      const cacheKeyHex = entry[0]
+      let elem: CodeCacheElement | undefined
+      if (this._lruCache) {
+        elem = this._lruCache.get(cacheKeyHex)
+      } else {
+        elem = this._orderedMapCache!.getElementByKey(cacheKeyHex)
+      }
+
+      if (elem !== undefined) {
+        items.push([cacheKeyHex, elem])
+      }
+    }
+    this._diffCache[this._checkpoints] = new Map<string, CodeCacheElement | undefined>()
+    return items
+  }
+
+  /**
+   * Revert changes to the cache to the last checkpoint (no effect on trie).
+   */
+  revert(): void {
+    this._checkpoints -= 1
+    if (this.DEBUG) {
+      this._debug(`Revert to checkpoint ${this._checkpoints}`)
+    }
+    const diffMap = this._diffCache.pop()!
+    for (const entry of diffMap.entries()) {
+      const addressHex = entry[0]
+      const elem = entry[1]
+      if (elem === undefined) {
+        if (this._lruCache) {
+          this._lruCache.delete(addressHex)
+        } else {
+          this._orderedMapCache!.eraseElementByKey(addressHex)
+        }
+      } else {
+        if (this._lruCache) {
+          this._lruCache.set(addressHex, elem)
+        } else {
+          this._orderedMapCache!.setElement(addressHex, elem)
+        }
+      }
+    }
+  }
+
+  /**
+   * Commits the current state of the cache (no effect on trie).
+   */
+  commit(): void {
+    this._checkpoints -= 1
+    if (this.DEBUG) {
+      this._debug(`Commit to checkpoint ${this._checkpoints}`)
+    }
+    const diffMap = this._diffCache.pop()!
+    for (const entry of diffMap.entries()) {
+      const addressHex = entry[0]
+      const oldEntry = this._diffCache[this._checkpoints].has(addressHex)
+      if (!oldEntry) {
+        const elem = entry[1]
+        this._diffCache[this._checkpoints].set(addressHex, elem)
+      }
+    }
+  }
+
+  /**
+   * Marks the current state of the cache as a checkpoint, which can
+   * later be reverted or committed.
+   */
+  checkpoint(): void {
+    this._checkpoints += 1
+    if (this.DEBUG) {
+      this._debug(`New checkpoint ${this._checkpoints}`)
+    }
+    this._diffCache.push(new Map<string, CodeCacheElement | undefined>())
+  }
+
+  /**
+   * Returns the size of the cache
+   * @returns
+   */
+  size() {
+    if (this._lruCache) {
+      return this._lruCache!.size
+    } else {
+      return this._orderedMapCache!.size()
+    }
+  }
+
+  /**
+   * Returns a dictionary with cache statistics.
+   *
+   * @param reset - Whether to reset statistics after retrieval.
+   * @returns A dictionary with cache statistics.
+   */
+  stats(reset = true): any {
+    const stats = { ...this._stats }
+    stats.size = this.size()
+    if (reset) {
+      this._stats = {
+        size: 0,
+        reads: 0,
+        hits: 0,
+        writes: 0,
+        deletions: 0,
+      }
+    }
+    return stats
+  }
+
+  /**
+   * Clears the cache.
+   */
+  clear(): void {
+    if (this.DEBUG) {
+      this._debug(`Clear cache`)
+    }
+    if (this._lruCache) {
+      this._lruCache.clear()
+    } else {
+      this._orderedMapCache!.clear()
+    }
+  }
+}

package/src/cache/index.ts

@@ -0,0 +1,6 @@
+export * from './account.ts'
+export * from './caches.ts'
+export * from './code.ts'
+export * from './originalStorageCache.ts'
+export * from './storage.ts'
+export * from './types.ts'