feat: introduce persistent cache for providers

- define a contract of the cache
- enable chain history and utxo providers to use injected cache
- create persistent cache storage
  - utilizing web extension storage
  - implementing the cache contract
  - having data envicting capability

Author: szymonmaslowski

packages/cardano-services-client/src/ChainHistoryProvider/BlockfrostChainHistoryProvider.ts

@@ -24,6 +24,7 @@ import {
 import { Logger } from 'ts-log';
 import omit from 'lodash/omit.js';
 import uniq from 'lodash/uniq.js';
+import type { Cache } from '@cardano-sdk/util';
 import type { Responses } from '@blockfrost/blockfrost-js';
 import type { Schemas } from '@blockfrost/blockfrost-js/lib/types/open-api';
 
@@ -33,12 +34,20 @@ export const DB_MAX_SAFE_INTEGER = 2_147_483_647;
 type BlockfrostTx = Pick<Responses['address_transactions_content'][0], 'block_height' | 'tx_index'>;
 const compareTx = (a: BlockfrostTx, b: BlockfrostTx) => a.block_height - b.block_height || a.tx_index - b.tx_index;
 
+type BlockfrostChainHistoryProviderDependencies = {
+  cache: Cache<Cardano.HydratedTx>;
+  client: BlockfrostClient;
+  networkInfoProvider: NetworkInfoProvider;
+  logger: Logger;
+};
+
 export class BlockfrostChainHistoryProvider extends BlockfrostProvider implements ChainHistoryProvider {
-  private readonly cache: Map<string, Cardano.HydratedTx> = new Map();
+  private readonly cache: Cache<Cardano.HydratedTx>;
   private networkInfoProvider: NetworkInfoProvider;
 
-  constructor(client: BlockfrostClient, networkInfoProvider: NetworkInfoProvider, logger: Logger) {
+  constructor({ cache, client, networkInfoProvider, logger }: BlockfrostChainHistoryProviderDependencies) {
     super(client, logger);
+    this.cache = cache;
     this.networkInfoProvider = networkInfoProvider;
   }
 
@@ -478,12 +487,12 @@ export class BlockfrostChainHistoryProvider extends BlockfrostProvider implement
   public async transactionsByHashes({ ids }: TransactionsByIdsArgs): Promise<Cardano.HydratedTx[]> {
     return Promise.all(
       ids.map(async (id) => {
-        if (this.cache.has(id)) {
-          return this.cache.get(id)!;
-        }
+        const cached = await this.cache.get(id);
+        if (cached) return cached;
+
         try {
           const fetchedTransaction = await this.fetchTransaction(id);
-          this.cache.set(id, fetchedTransaction);
+          void this.cache.set(id, fetchedTransaction);
           return fetchedTransaction;
         } catch (error) {
           throw this.toProviderError(error);

packages/cardano-services-client/src/UtxoProvider/BlockfrostUtxoProvider.ts

@@ -1,9 +1,22 @@
-import { BlockfrostProvider, BlockfrostToCore, fetchSequentially } from '../blockfrost';
+import { BlockfrostClient, BlockfrostProvider, BlockfrostToCore, fetchSequentially } from '../blockfrost';
 import { Cardano, Serialization, UtxoByAddressesArgs, UtxoProvider } from '@cardano-sdk/core';
+import { Logger } from 'ts-log';
+import type { Cache } from '@cardano-sdk/util';
 import type { Responses } from '@blockfrost/blockfrost-js';
 
+type BlockfrostUtxoProviderDependencies = {
+  client: BlockfrostClient;
+  cache: Cache<Cardano.Tx>;
+  logger: Logger;
+};
+
 export class BlockfrostUtxoProvider extends BlockfrostProvider implements UtxoProvider {
-  private readonly cache: Map<string, Cardano.Tx> = new Map();
+  private readonly cache: Cache<Cardano.Tx>;
+
+  constructor({ cache, client, logger }: BlockfrostUtxoProviderDependencies) {
+    super(client, logger);
+    this.cache = cache;
+  }
 
   protected async fetchUtxos(addr: Cardano.PaymentAddress, paginationQueryString: string): Promise<Cardano.Utxo[]> {
     const queryString = `addresses/${addr.toString()}/utxos?${paginationQueryString}`;
@@ -29,9 +42,8 @@ export class BlockfrostUtxoProvider extends BlockfrostProvider implements UtxoPr
       });
   }
   protected async fetchDetailsFromCBOR(hash: string) {
-    if (this.cache.has(hash)) {
-      return this.cache.get(hash);
-    }
+    const cached = await this.cache.get(hash);
+    if (cached) return cached;
 
     const result = await this.fetchCBOR(hash)
       .then((cbor) => {
@@ -48,7 +60,7 @@ export class BlockfrostUtxoProvider extends BlockfrostProvider implements UtxoPr
       return null;
     }
 
-    this.cache.set(hash, result);
+    void this.cache.set(hash, result);
     return result;
   }
 

packages/util/src/types.ts

@@ -28,3 +28,8 @@ type Impossible<K extends keyof any> = {
   [P in K]: never;
 };
 export type NoExtraProperties<T, U> = U & Impossible<Exclude<keyof U, keyof T>>;
+
+export type Cache<T> = {
+  get(key: string): Promise<T | undefined>;
+  set(key: string, value: T): Promise<void>;
+};

packages/web-extension/src/index.ts

@@ -4,3 +4,4 @@ export * from './supplyDistributionTracker';
 export * from './keyAgent';
 export * from './walletManager';
 export * as cip30 from './cip30';
+export * from './storage';

packages/web-extension/src/storage/index.ts

@@ -0,0 +1 @@
+export * from './persistentCacheStorage';

packages/web-extension/src/storage/persistentCacheStorage.ts

@@ -0,0 +1,107 @@
+import { Storage, storage } from 'webextension-polyfill';
+import StorageArea = Storage.StorageArea;
+
+type MetadataItem = {
+  accessTime: number;
+};
+
+type Metadata = Record<string, MetadataItem>;
+
+const sizeOfChunkToBePurged = 0.1;
+
+const isGetBytesInUsePresent = (
+  storageLocal: StorageArea
+): storageLocal is StorageArea & { getBytesInUse: (keys?: string | string[]) => Promise<number> } =>
+  'getBytesInUse' in storageLocal;
+
+export const createPersistentCacheStorage = <T>({
+  fallbackMaxCollectionItemsGuard,
+  resourceName,
+  quotaInBytes
+}: {
+  fallbackMaxCollectionItemsGuard: number;
+  resourceName: string;
+  quotaInBytes: number;
+}) => {
+  const loaded = new Map<string, T>();
+  const metadataKey = `${resourceName}-metadata`;
+  const getItemKey = (key: string) => `${resourceName}-item-${key}`;
+
+  const getMetadata = async () => {
+    const result = await storage.local.get(metadataKey);
+    return result[metadataKey] as Metadata;
+  };
+
+  const updateAccessTime = async (key: string) => {
+    const metadata = await getMetadata();
+    const nextMetadata: Metadata = {
+      ...metadata,
+      [key]: {
+        accessTime: Date.now()
+      }
+    };
+    await storage.local.set({ [metadataKey]: nextMetadata });
+  };
+
+  const isQuotaExceeded = async () => {
+    const metadata = await getMetadata();
+    const allCollectionKeys = [metadataKey, ...Object.keys(metadata)];
+
+    // Polyfill we use does not list the getBytesInUse method but that method exists in chrome API
+    if (isGetBytesInUsePresent(storage.local)) {
+      const bytesInUse = await storage.local.getBytesInUse(allCollectionKeys);
+      return bytesInUse > quotaInBytes;
+    }
+
+    return allCollectionKeys.length > fallbackMaxCollectionItemsGuard;
+  };
+
+  const evict = async () => {
+    let metadata = await getMetadata();
+    const mostDatedKeysToPurge = Object.entries(metadata)
+      .map(([key, { accessTime }]) => ({ accessTime, key }))
+      .sort((a, b) => a.accessTime - b.accessTime)
+      .filter((_, index, self) => {
+        const numberOfItemsToPurge = Math.abs(self.length * sizeOfChunkToBePurged);
+        return index < numberOfItemsToPurge;
+      })
+      .map((i) => i.key);
+
+    await storage.local.remove(mostDatedKeysToPurge);
+    metadata = await getMetadata();
+    for (const key of mostDatedKeysToPurge) {
+      delete metadata[key];
+    }
+    await storage.local.set({ [metadataKey]: metadata });
+  };
+
+  return {
+    async get(key: string) {
+      const itemKey = getItemKey(key);
+
+      let value = loaded.get(key);
+      if (!value) {
+        const result = await storage.local.get(itemKey);
+        value = result[itemKey];
+      }
+
+      if (value) {
+        void updateAccessTime(itemKey);
+      }
+
+      return value;
+    },
+    async set(key: string, value: T) {
+      const itemKey = getItemKey(key);
+      loaded.set(itemKey, value);
+      await storage.local.set({ [itemKey]: value });
+
+      void (async () => {
+        await updateAccessTime(itemKey);
+        if (await isQuotaExceeded()) await evict();
+      })();
+    }
+  };
+};
+
+export type CreatePersistentCacheStorage = typeof createPersistentCacheStorage;