@talismn/balances-react 0.3.3 → 0.4.1

package/dist/talismn-balances-react.esm.js

@@ -1,16 +1,182 @@
-import { Balances, db, balances } from '@talismn/balances';
+import { useContext, createContext, useState, useEffect, useMemo, useRef, useCallback } from 'react';
+import { jsx } from 'react/jsx-runtime';
 import { ChainConnector } from '@talismn/chain-connector';
 import { ChainConnectorEvm } from '@talismn/chain-connector-evm';
+import { connectionMetaDb } from '@talismn/connection-meta';
+import { ChaindataProviderExtension } from '@talismn/chaindata-provider-extension';
+import { db as db$1, createSubscriptionId, deleteSubscriptionId, balances, BalanceStatusLive, Balances, deriveStatuses, getValidSubscriptionIds } from '@talismn/balances';
+import { db, fetchTokenRates } from '@talismn/token-rates';
 import { useLiveQuery } from 'dexie-react-hooks';
-import { useState, useEffect, useRef } from 'react';
 import { useDebounce } from 'react-use';
+import md5 from 'blueimp-md5';
 import anylogger from 'anylogger';
-import { ChaindataProviderExtension } from '@talismn/chaindata-provider-extension';
-import { fetchTokenRates } from '@talismn/token-rates';
+import { Subject, Observable, defer, shareReplay } from 'rxjs';
+
+const provideContext = useProviderContext => {
+  // automatic typing based on our hook's return type
+
+  const Context = /*#__PURE__*/createContext({
+    __provideContextInternalDefaultValue: true
+  });
+  const Provider = ({
+    children,
+    ...props
+  }) => {
+    const ctx = useProviderContext(props);
+    return /*#__PURE__*/jsx(Context.Provider, {
+      value: ctx,
+      children: children
+    });
+  };
+  const useProvidedContext = () => {
+    const context = useContext(Context);
+    if (typeof context === "object" && context && "__provideContextInternalDefaultValue" in context) throw new Error("This hook requires a provider to be present above it in the tree");
+    return context;
+  };
+  const result = [Provider, useProvidedContext];
+  return result;
+};
+
+const useAllAddressesProvider = () => useState([]);
+const [AllAddressesProvider, useAllAddresses] = provideContext(useAllAddressesProvider);
+
+function useChaindataProvider(options = {}) {
+  const [onfinalityApiKey, setOnfinalityApiKey] = useState(options.onfinalityApiKey);
+
+  // make sure we recreate provider only when the onfinalityApiKey changes
+  useEffect(() => {
+    if (options.onfinalityApiKey !== onfinalityApiKey) setOnfinalityApiKey(options.onfinalityApiKey);
+  }, [options.onfinalityApiKey, onfinalityApiKey]);
+  return useMemo(() => new ChaindataProviderExtension({
+    onfinalityApiKey
+  }), [onfinalityApiKey]);
+}
+const [ChaindataProvider, useChaindata] = provideContext(useChaindataProvider);
+
+function useChainConnectorsProvider(options) {
+  const [onfinalityApiKey, setOnfinalityApiKey] = useState(options.onfinalityApiKey);
+
+  // make sure we recreate provider only when the onfinalityApiKey changes
+  useEffect(() => {
+    if (options.onfinalityApiKey !== onfinalityApiKey) setOnfinalityApiKey(options.onfinalityApiKey);
+  }, [options.onfinalityApiKey, onfinalityApiKey]);
+
+  // chaindata dependency
+  const chaindata = useChaindata();
+
+  // substrate connector
+  const substrate = useMemo(() => new ChainConnector(chaindata, connectionMetaDb), [chaindata]);
+
+  // evm connector
+  const evm = useMemo(() => new ChainConnectorEvm(chaindata, {
+    onfinalityApiKey
+  }), [chaindata, onfinalityApiKey]);
+  return useMemo(() => ({
+    substrate,
+    evm
+  }), [substrate, evm]);
+}
+const [ChainConnectorsProvider, useChainConnectors] = provideContext(useChainConnectorsProvider);
+
+const useBalanceModulesProvider = ({
+  balanceModules
+}) => {
+  const chainConnectors = useChainConnectors();
+  const chaindataProvider = useChaindata();
+  const hydrated = useMemo(() => chainConnectors.substrate && chainConnectors.evm && chaindataProvider ? balanceModules.map(mod => mod({
+    chainConnectors,
+    chaindataProvider
+  })) : [], [balanceModules, chainConnectors, chaindataProvider]);
+  return hydrated;
+};
+const [BalanceModulesProvider, useBalanceModules] = provideContext(useBalanceModulesProvider);
+
+const filterNoTestnet = ({
+  isTestnet
+}) => isTestnet === false;
+const DEFAULT_VALUE = {
+  chainsWithTestnets: [],
+  chainsWithoutTestnets: [],
+  evmNetworksWithTestnets: [],
+  evmNetworksWithoutTestnets: [],
+  tokensWithTestnets: [],
+  tokensWithoutTestnets: [],
+  chainsWithTestnetsMap: {},
+  chainsWithoutTestnetsMap: {},
+  evmNetworksWithTestnetsMap: {},
+  evmNetworksWithoutTestnetsMap: {},
+  tokensWithTestnetsMap: {},
+  tokensWithoutTestnetsMap: {},
+  tokenRatesMap: {},
+  balances: []
+};
+const consolidateDbCache = (chainsMap, evmNetworksMap, tokensMap, tokenRates, allBalances) => {
+  if (!chainsMap || !evmNetworksMap || !tokensMap || !tokenRates || !allBalances) return DEFAULT_VALUE;
+  const chainsWithTestnets = Object.values(chainsMap);
+  const chainsWithoutTestnets = chainsWithTestnets.filter(filterNoTestnet);
+  const chainsWithoutTestnetsMap = Object.fromEntries(chainsWithoutTestnets.map(network => [network.id, network]));
+  const evmNetworksWithTestnets = Object.values(evmNetworksMap);
+  const evmNetworksWithoutTestnets = evmNetworksWithTestnets.filter(filterNoTestnet);
+  const evmNetworksWithoutTestnetsMap = Object.fromEntries(evmNetworksWithoutTestnets.map(network => [network.id, network]));
+
+  // ensure that we have corresponding network for each token
+  const tokensWithTestnets = Object.values(tokensMap).filter(token => token.chain && chainsMap[token.chain.id] || token.evmNetwork && evmNetworksMap[token.evmNetwork.id]);
+  const tokensWithoutTestnets = tokensWithTestnets.filter(filterNoTestnet).filter(token => token.chain && chainsWithoutTestnetsMap[token.chain.id] || token.evmNetwork && evmNetworksWithoutTestnetsMap[token.evmNetwork.id]);
+  const tokensWithTestnetsMap = Object.fromEntries(tokensWithTestnets.map(token => [token.id, token]));
+  const tokensWithoutTestnetsMap = Object.fromEntries(tokensWithoutTestnets.map(token => [token.id, token]));
+  const tokenRatesMap = Object.fromEntries(tokenRates.map(({
+    tokenId,
+    rates
+  }) => [tokenId, rates]));
+
+  // return only balances for which we have a token
+  const balances = allBalances.filter(b => tokensWithTestnetsMap[b.tokenId]);
+  return {
+    chainsWithTestnets,
+    chainsWithoutTestnets,
+    evmNetworksWithTestnets,
+    evmNetworksWithoutTestnets,
+    tokensWithTestnets,
+    tokensWithoutTestnets,
+    chainsWithTestnetsMap: chainsMap,
+    chainsWithoutTestnetsMap,
+    evmNetworksWithTestnetsMap: evmNetworksMap,
+    evmNetworksWithoutTestnetsMap,
+    tokensWithTestnetsMap,
+    tokensWithoutTestnetsMap,
+    tokenRatesMap,
+    balances
+  };
+};
+const useDbCacheProvider = () => {
+  const chaindataProvider = useChaindata();
+  const chainList = useLiveQuery(() => chaindataProvider?.chains(), [chaindataProvider]);
+  const evmNetworkList = useLiveQuery(() => chaindataProvider?.evmNetworks(), [chaindataProvider]);
+  const tokenList = useLiveQuery(() => chaindataProvider?.tokens(), [chaindataProvider]);
+  const tokenRates = useLiveQuery(() => db.tokenRates.toArray(), []);
+  const rawBalances = useLiveQuery(() => db$1.balances.toArray(), []);
+  const [dbData, setDbData] = useState(DEFAULT_VALUE);
+
+  // debounce every 500ms to prevent hammering UI with updates
+  useDebounce(() => {
+    setDbData(consolidateDbCache(chainList, evmNetworkList, tokenList, tokenRates, rawBalances));
+  }, 500, [chainList, evmNetworkList, tokenList, tokenRates, rawBalances]);
+  const refInitialized = useRef(false);
+
+  // force an update as soon as all datasources are fetched, so UI can display data ASAP
+  useEffect(() => {
+    if (!refInitialized.current && chainList && evmNetworkList && tokenList && tokenRates && rawBalances) {
+      setDbData(consolidateDbCache(chainList, evmNetworkList, tokenList, tokenRates, rawBalances));
+      refInitialized.current = true;
+    }
+  }, [chainList, evmNetworkList, tokenList, tokenRates, rawBalances]);
+  return dbData;
+};
+const [DbCacheProvider, useDbCache] = provideContext(useDbCacheProvider);
 
 var packageJson = {
 	name: "@talismn/balances-react",
-	version: "0.3.3",
+	version: "0.4.1",
 	author: "Talisman",
 	homepage: "https://talisman.xyz",
 	license: "UNLICENSED",
@@ -28,28 +194,31 @@ var packageJson = {
 		"/dist"
 	],
 	engines: {
-		node: ">=14"
+		node: ">=18"
 	},
 	scripts: {
 		test: "jest",
-		lint: "eslint . --max-warnings 0",
+		lint: "eslint src --max-warnings 0",
 		clean: "rm -rf dist && rm -rf .turbo rm -rf node_modules"
 	},
 	dependencies: {
-		"@talismn/balances": "workspace:^",
-		"@talismn/chain-connector": "workspace:^",
-		"@talismn/chain-connector-evm": "workspace:^",
-		"@talismn/chaindata-provider": "workspace:^",
-		"@talismn/chaindata-provider-extension": "workspace:^",
-		"@talismn/token-rates": "workspace:^",
+		"@talismn/balances": "workspace:*",
+		"@talismn/chain-connector": "workspace:*",
+		"@talismn/chain-connector-evm": "workspace:*",
+		"@talismn/chaindata-provider": "workspace:*",
+		"@talismn/chaindata-provider-extension": "workspace:*",
+		"@talismn/connection-meta": "workspace:*",
+		"@talismn/token-rates": "workspace:*",
 		anylogger: "^1.0.11",
-		dexie: "^3.2.2",
-		"dexie-react-hooks": "^1.1.1",
-		"react-use": "^17.4.0"
+		"blueimp-md5": "2.19.0",
+		dexie: "^3.2.3",
+		"dexie-react-hooks": "^1.1.3",
+		"react-use": "^17.4.0",
+		rxjs: "^7.8.1"
 	},
 	devDependencies: {
-		"@talismn/eslint-config": "workspace:^",
-		"@talismn/tsconfig": "workspace:^",
+		"@talismn/eslint-config": "workspace:*",
+		"@talismn/tsconfig": "workspace:*",
 		"@types/jest": "^27.5.1",
 		"@types/react": "^18.0.17",
 		eslint: "^8.4.0",
@@ -72,139 +241,394 @@ var packageJson = {
 
 var log = anylogger(packageJson.name);
 
-// TODO: Allow user to call useChaindata from multiple places
-function useChaindata(options = {}) {
-  const [chaindataProvider, setChaindataProvider] = useState(null);
+// global data store containing all subscriptions
+const subscriptions = {};
 
-  // this number is incremented each time the chaindataProvider has fetched new data
-  const [generation, setGeneration] = useState(0);
+/**
+ * This hook ensures a subscription is created only once, and unsubscribe automatically as soon as there is no consumer to the hook
+ * @param key key that is unique to the subscription's parameters
+ * @param subscribe // subscribe function that will be shared by all consumers of the key
+ */
+const useSharedSubscription = (key, subscribe) => {
+  // create the rxJS subject if it doesn't exist
+  if (!subscriptions[key]) subscriptions[key] = {
+    subject: new Subject()
+  };
   useEffect(() => {
-    const chaindataProvider = new ChaindataProviderExtension({
-      onfinalityApiKey: options.onfinalityApiKey
-    });
-    let shouldHydrate = true;
-    const timer = 300_000; // 300_000ms = 300s = 5 minutes
-    const hydrate = async () => {
-      if (!shouldHydrate) return;
-      try {
-        const updated = await chaindataProvider.hydrate();
-        if (updated) setGeneration(generation => (generation + 1) % Number.MAX_SAFE_INTEGER);
-        setTimeout(hydrate, timer);
-      } catch (error) {
-        const retryTimeout = 5_000; // 5_000ms = 5 seconds
-        log.error(`Failed to fetch chaindata, retrying in ${Math.round(retryTimeout / 1000)} seconds`, error);
-        setTimeout(hydrate, retryTimeout);
+    // subscribe to subject.
+    // it won't change but we need to count subscribers, to unsubscribe main subscription when no more observers
+    const s = subscriptions[key].subject.subscribe();
+    return () => {
+      // unsubscribe from our local observable updates to prevent memory leaks
+      s.unsubscribe();
+      const {
+        subject,
+        unsubscribe
+      } = subscriptions[key];
+      if (!subject.observed && unsubscribe) {
+        log.debug(`[useSharedSubscription] unsubscribing ${key}`);
+
+        // unsubscribe from backend updates to prevent unnecessary network connections
+        unsubscribe();
+        delete subscriptions[key].unsubscribe;
       }
     };
-    setChaindataProvider(chaindataProvider);
-    hydrate();
+  }, [key]);
+
+  // Initialize subscription
+  useEffect(() => {
+    const {
+      unsubscribe
+    } = subscriptions[key];
+    // launch the subscription if it's a new key
+    if (!unsubscribe) {
+      const cb = subscribe();
+      log.debug(`[useSharedSubscription] subscribing ${key}`);
+      if (cb) subscriptions[key].unsubscribe = cb;
+      // this error should only happen when developping a new hook, let it bubble up
+      else throw new Error(`${key} subscribe did not return an unsubscribe callback`);
+    }
+  }, [key, subscribe]);
+};
+
+/**
+ * Creates a subscription function that can be used to subscribe to a multicast observable created from an upstream source.
+ *
+ * An example of when this is useful is when we want to subscribe to some data from multiple components, but we only want
+ * to actively keep that data hydrated when at least one component is subscribed to it.
+ *
+ * When the first component subscribes, the `upstream` function will be called. It should then set up a subscription and return a teardown function.
+ * When subsequent components subscribe, they will be added to the existing subscription.
+ * When the last component unsubscribes, the teardown function returned from the `upstream` function will be called.
+ *
+ * @param upstream A function that takes a "next" callback function as an argument, and returns either an unsubscribe function or void.
+ * @returns A subscription function that can be used to subscribe to the multicast observable.
+ */
+const useMulticastSubscription = upstream => {
+  const subscribe = useMemo(() => createMulticastSubscription(upstream), [upstream]);
+  return subscribe;
+};
+const createMulticastSubscription = upstream => {
+  // Create an upstream observable using the provided function.
+  const upstreamObservable = new Observable(subscriber => {
+    const unsubscribe = upstream(val => subscriber.next(val));
     return () => {
-      shouldHydrate = false;
+      typeof unsubscribe === "function" && unsubscribe();
     };
-  }, [options.onfinalityApiKey]);
-  if (chaindataProvider) chaindataProvider.generation = generation;
-  return chaindataProvider;
+  });
+
+  // Create a multicast observable from the upstream observable, using the shareReplay operator.
+  const multicastObservable = defer(() => upstreamObservable).pipe(shareReplay({
+    bufferSize: 1,
+    refCount: true
+  }));
+
+  // Create a subscription function that subscribes to the multicast observable and returns an unsubscribe function.
+  const subscribe = callback => {
+    const subscription = multicastObservable.subscribe(callback);
+    const unsubscribe = () => subscription.unsubscribe();
+    return unsubscribe;
+  };
+  return subscribe;
+};
+
+const useWithTestnetsProvider = ({
+  withTestnets
+}) => {
+  return {
+    withTestnets
+  };
+};
+const [WithTestnetsProvider, useWithTestnets] = provideContext(useWithTestnetsProvider);
+
+/**
+ * This hook is responsible for fetching the data used for balances and inserting it into the db.
+ */
+const useDbCacheSubscription = subscribeTo => {
+  const provider = useChaindata();
+
+  // can't handle balances & tokenRates here as they have other dependencies, it would trigger to many subscriptions
+  const subscribe = useCallback(() => {
+    switch (subscribeTo) {
+      case "chains":
+        return subscribeChainDataHydrate(provider, "chains");
+      case "evmNetworks":
+        return subscribeChainDataHydrate(provider, "evmNetworks");
+      case "tokens":
+        return subscribeChainDataHydrate(provider, "tokens");
+    }
+  }, [provider, subscribeTo]);
+  useSharedSubscription(subscribeTo, subscribe);
+};
+
+/**
+ * This hook is responsible for fetching the data used for token rates and inserting it into the db.
+ */
+function useDbCacheTokenRatesSubscription() {
+  const {
+    withTestnets
+  } = useWithTestnets();
+  const tokens = useTokens$1(withTestnets);
+  const subscriptionKey = useMemo(
+  // not super sexy but we need key to change based on this stuff
+  () => {
+    const key = Object.values(tokens ?? {}).map(({
+      id
+    }) => id).sort().join();
+    return `tokenRates-${md5(key)}`;
+  }, [tokens]);
+  const subscription = useCallback(() => {
+    if (!Object.values(tokens ?? {}).length) return () => {};
+    return subscribeTokenRates(tokens);
+  }, [tokens]);
+  useSharedSubscription(subscriptionKey, subscription);
 }
-function useChains(chaindata) {
-  const [chains, setChains] = useState();
-  useEffect(() => {
-    if (!chaindata) return;
-    const thisGeneration = chaindata.generation;
-    chaindata.chains().then(chains => {
-      if (thisGeneration !== chaindata.generation) return;
-      setChains(chains);
+
+/**
+ * This hook is responsible for fetching the data used for balances and inserting it into the db.
+ */
+function useDbCacheBalancesSubscription() {
+  const {
+    withTestnets
+  } = useWithTestnets();
+  const balanceModules = useBalanceModules();
+  const chaindataProvider = useChaindata();
+  const chainConnectors = useChainConnectors();
+  const [allAddresses] = useAllAddresses();
+  const tokens = useTokens$1(withTestnets);
+  const subscriptionKey = useMemo(
+  // not super sexy but we need key to change based on this stuff
+  () => {
+    const key = allAddresses.sort().join().concat(...Object.values(tokens ?? {}).map(({
+      id
+    }) => id).sort()).concat(`evm:${!!chainConnectors.evm}`, `sub:${!!chainConnectors.substrate}`, ...balanceModules.map(m => m.type).sort(), `cd:${!!chaindataProvider}`);
+    return `balances-${md5(key)}`;
+  }, [allAddresses, balanceModules, chainConnectors, chaindataProvider, tokens]);
+  const subscription = useCallback(() => {
+    if (!Object.values(tokens ?? {}).length || !allAddresses.length) return () => {};
+    return subscribeBalances(tokens ?? {}, allAddresses, balanceModules);
+  }, [allAddresses, balanceModules, tokens]);
+  useSharedSubscription(subscriptionKey, subscription);
+}
+
+// subscriptionless version of useTokens, prevents circular dependency
+const useTokens$1 = withTestnets => {
+  const {
+    tokensWithTestnetsMap,
+    tokensWithoutTestnetsMap
+  } = useDbCache();
+  return withTestnets ? tokensWithTestnetsMap : tokensWithoutTestnetsMap;
+};
+const subscribeChainDataHydrate = (provider, type) => {
+  const chaindata = provider;
+  const delay = 300_000; // 300_000ms = 300s = 5 minutes
+
+  let timeout = null;
+  const hydrate = async () => {
+    try {
+      if (type === "chains") await chaindata.hydrateChains();
+      if (type === "evmNetworks") await chaindata.hydrateEvmNetworks();
+      if (type === "tokens") await chaindata.hydrateTokens();
+      timeout = setTimeout(hydrate, delay);
+    } catch (error) {
+      const retryTimeout = 5_000; // 5_000ms = 5 seconds
+      log.error(`Failed to fetch chaindata, retrying in ${Math.round(retryTimeout / 1000)} seconds`, error);
+      timeout = setTimeout(hydrate, retryTimeout);
+    }
+  };
+
+  // launch the loop
+  hydrate();
+  return () => {
+    if (timeout) clearTimeout(timeout);
+  };
+};
+const subscribeTokenRates = tokens => {
+  const REFRESH_INTERVAL = 300_000; // 6 minutes
+  const RETRY_INTERVAL = 5_000; // 5 sec
+
+  let timeout = null;
+  const refreshTokenRates = async () => {
+    try {
+      if (timeout) clearTimeout(timeout);
+      const tokenRates = await fetchTokenRates(tokens);
+      const putTokenRates = Object.entries(tokenRates).map(([tokenId, rates]) => ({
+        tokenId,
+        rates
+      }));
+      db.transaction("rw", db.tokenRates, async () => await db.tokenRates.bulkPut(putTokenRates));
+      timeout = setTimeout(() => {
+        refreshTokenRates();
+      }, REFRESH_INTERVAL);
+    } catch (error) {
+      log.error(`Failed to fetch tokenRates, retrying in ${Math.round(RETRY_INTERVAL / 1000)} seconds`, error);
+      setTimeout(async () => {
+        refreshTokenRates();
+      }, RETRY_INTERVAL);
+    }
+  };
+
+  // launch the loop
+  refreshTokenRates();
+  return () => {
+    if (timeout) clearTimeout(timeout);
+  };
+};
+const subscribeBalances = (tokens, addresses, balanceModules) => {
+  const tokenIds = Object.values(tokens).map(({
+    id
+  }) => id);
+  const addressesByToken = Object.fromEntries(tokenIds.map(tokenId => [tokenId, addresses]));
+  const subscriptionId = createSubscriptionId();
+
+  // TODO: Create subscriptions in a service worker, where we can detect page closes
+  // and therefore reliably delete the subscriptionId when the user closes our dapp
+  //
+  // For more information, check out https://developer.chrome.com/blog/page-lifecycle-api/#faqs
+  // and scroll down to:
+  // - `What is the back/forward cache?`, and
+  // - `If I can't run asynchronous APIs in the frozen or terminated states, how can I save data to IndexedDB?
+  //
+  // For now, we'll just last-ditch remove the subscriptionId (it works surprisingly well!) in the beforeunload event
+  window.onbeforeunload = () => {
+    deleteSubscriptionId();
+  };
+  const updateDb = balances => {
+    const putBalances = Object.entries(balances.toJSON()).map(([id, balance]) => ({
+      id,
+      ...balance,
+      status: BalanceStatusLive(subscriptionId)
+    }));
+    db$1.transaction("rw", db$1.balances, async () => await db$1.balances.bulkPut(putBalances));
+  };
+  let unsubscribed = false;
+
+  // eslint-disable-next-line no-console
+  log.log("subscribing to balance changes for %d tokens and %d addresses", tokenIds.length, addresses.length);
+  const unsubs = balanceModules.map(async balanceModule => {
+    // filter out tokens to only include those which this module knows how to fetch balances for
+    const moduleTokenIds = Object.values(tokens ?? {}).filter(({
+      type
+    }) => type === balanceModule.type).map(({
+      id
+    }) => id);
+    const addressesByModuleToken = Object.fromEntries(Object.entries(addressesByToken).filter(([tokenId]) => moduleTokenIds.includes(tokenId)));
+    const unsub = balances(balanceModule, addressesByModuleToken, (error, balances) => {
+      // log errors
+      if (error) {
+        if (error?.type === "STALE_RPC_ERROR" || error?.type === "WEBSOCKET_ALLOCATION_EXHAUSTED_ERROR") return db$1.balances.where({
+          source: balanceModule.type,
+          chainId: error.chainId
+        }).filter(balance => {
+          if (!Object.keys(addressesByModuleToken).includes(balance.tokenId)) return false;
+          if (!addressesByModuleToken[balance.tokenId].includes(balance.address)) return false;
+          return true;
+        }).modify({
+          status: "stale"
+        });
+        return log.error(`Failed to fetch ${balanceModule.type} balances`, error);
+      }
+      // ignore empty balance responses
+      if (!balances) return;
+      // ignore balances from old subscriptions which are still in the process of unsubscribing
+      if (unsubscribed) return;
+      updateDb(balances);
     });
-  }, [chaindata, chaindata?.generation]);
-  return chains || {};
+    return () => {
+      // wait 2 seconds before actually unsubscribing, allowing for websocket to be reused
+      unsub.then(unsubscribe => {
+        setTimeout(unsubscribe, 2_000);
+      });
+      deleteSubscriptionId();
+    };
+  });
+  const unsubscribeAll = () => {
+    unsubscribed = true;
+    unsubs.forEach(unsub => unsub.then(unsubscribe => unsubscribe()));
+  };
+  return unsubscribeAll;
+};
+
+function useChains(withTestnets) {
+  // keep db data up to date
+  useDbCacheSubscription("chains");
+  const {
+    chainsWithTestnetsMap,
+    chainsWithoutTestnetsMap
+  } = useDbCache();
+  return withTestnets ? chainsWithTestnetsMap : chainsWithoutTestnetsMap;
 }
-function useChain(chaindata, chainId) {
-  const [chain, setChain] = useState();
-  useEffect(() => {
-    if (chaindata === null) return;
-    if (!chainId) return;
-    chaindata.getChain(chainId).then(setChain);
-  }, [chainId, chaindata, chaindata?.generation]);
-  return chain;
+function useChain(chainId, withTestnets) {
+  const chains = useChains(withTestnets);
+  return chainId ? chains[chainId] : undefined;
 }
-function useEvmNetworks(chaindata) {
-  const [evmNetworks, setEvmNetworks] = useState();
-  useEffect(() => {
-    if (!chaindata) return;
-    const thisGeneration = chaindata.generation;
-    chaindata.evmNetworks().then(evmNetworks => {
-      if (thisGeneration !== chaindata.generation) return;
-      setEvmNetworks(evmNetworks);
-    });
-  }, [chaindata, chaindata?.generation]);
-  return evmNetworks || {};
+
+function useEvmNetworks(withTestnets) {
+  // keep db data up to date
+  useDbCacheSubscription("evmNetworks");
+  const {
+    evmNetworksWithTestnetsMap,
+    evmNetworksWithoutTestnetsMap
+  } = useDbCache();
+  return withTestnets ? evmNetworksWithTestnetsMap : evmNetworksWithoutTestnetsMap;
 }
-function useEvmNetwork(chaindata, evmNetworkId) {
-  const [evmNetwork, setEvmNetwork] = useState();
-  useEffect(() => {
-    if (chaindata === null) return;
-    if (!evmNetworkId) return;
-    chaindata.getEvmNetwork(evmNetworkId).then(setEvmNetwork);
-  }, [chaindata, chaindata?.generation, evmNetworkId]);
-  return evmNetwork;
+function useEvmNetwork(evmNetworkId, withTestnets) {
+  const evmNetworks = useEvmNetworks(withTestnets);
+  return evmNetworkId ? evmNetworks[evmNetworkId] : undefined;
 }
-function useTokens(chaindata) {
-  const [tokens, setTokens] = useState();
-  useEffect(() => {
-    if (!chaindata) return;
-    const thisGeneration = chaindata.generation;
-    chaindata.tokens().then(tokens => {
-      if (thisGeneration !== chaindata.generation) return;
-      setTokens(tokens);
-    });
-  }, [chaindata, chaindata?.generation]);
-  return tokens || {};
+
+function useTokenRates() {
+  // keep db data up to date
+  useDbCacheTokenRatesSubscription();
+  const {
+    tokenRatesMap
+  } = useDbCache();
+  return tokenRatesMap;
 }
-function useToken(chaindata, tokenId) {
-  const [token, setToken] = useState();
-  useEffect(() => {
-    if (chaindata === null) return;
-    if (!tokenId) return;
-    chaindata.getToken(tokenId).then(setToken);
-  }, [chaindata, chaindata?.generation, tokenId]);
-  return token;
+function useTokenRate(tokenId) {
+  const tokenRates = useTokenRates();
+  return tokenId ? tokenRates[tokenId] : undefined;
 }
 
-function useTokenRates(tokens) {
-  const generation = useRef(0);
-  const [tokenRates, setTokenRates] = useState();
-  useEffect(() => {
-    if (!tokens) return;
-    if (Object.keys(tokens).length < 1) return;
-
-    // when we make a new request, we want to ignore any old requests which haven't yet completed
-    // otherwise we risk replacing the most recent data with older data
-    generation.current = (generation.current + 1) % Number.MAX_SAFE_INTEGER;
-    const thisGeneration = generation.current;
-    fetchTokenRates(tokens).then(tokenRates => {
-      if (thisGeneration !== generation.current) return;
-      setTokenRates(tokenRates);
-    });
-  }, [tokens]);
-  return tokenRates || {};
+function useTokens(withTestnets) {
+  // keep db data up to date
+  useDbCacheSubscription("tokens");
+  const {
+    tokensWithTestnetsMap,
+    tokensWithoutTestnetsMap
+  } = useDbCache();
+  return withTestnets ? tokensWithTestnetsMap : tokensWithoutTestnetsMap;
+}
+function useToken(tokenId, withTestnets) {
+  const tokens = useTokens(withTestnets);
+  return tokenId ? tokens[tokenId] : undefined;
 }
 
-// TODO: Add the equivalent functionalty of `useDbCache` directly to this library.
-//
-//       How it will work:
-//
-//       useChains/useEvmNetworks/useTokens/useTokenRates will all make use of a
-//       useCachedDb hook, which internally subscribes to all of the db tables
-//       for everything, and then filters the subscribed data based on what params
-//       the caller of useChains/useTokens/etc has provided.
-function useBalances(
-// TODO: Make this array of BalanceModules more type-safe
-balanceModules, chaindataProvider, addressesByToken, options = {}) {
-  useBalancesSubscriptions(balanceModules, chaindataProvider, addressesByToken, options);
-  const chains = useChains(chaindataProvider);
-  const evmNetworks = useEvmNetworks(chaindataProvider);
-  const tokens = useTokens(chaindataProvider);
-  const tokenRates = useTokenRates(tokens);
-  const balances = useLiveQuery(async () => new Balances(await db.balances.filter(balance => {
+const useBalancesHydrate = () => {
+  const {
+    withTestnets
+  } = useWithTestnets();
+  const chains = useChains(withTestnets);
+  const evmNetworks = useEvmNetworks(withTestnets);
+  const tokens = useTokens(withTestnets);
+  const tokenRates = useTokenRates();
+  return useMemo(() => ({
+    chains,
+    evmNetworks,
+    tokens,
+    tokenRates
+  }), [chains, evmNetworks, tokens, tokenRates]);
+};
+
+function useBalances(addressesByToken) {
+  // keep db data up to date
+  useDbCacheBalancesSubscription();
+  const balanceModules = useBalanceModules();
+  const {
+    balances
+  } = useDbCache();
+  const hydrate = useBalancesHydrate();
+  return useMemo(() => new Balances(deriveStatuses([...getValidSubscriptionIds()], balances.filter(balance => {
     // check that this balance is included in our queried balance modules
     if (!balanceModules.map(({
       type
@@ -221,136 +645,60 @@ balanceModules, chaindataProvider, addressesByToken, options = {}) {
 
     // keep this balance
     return true;
-  }).toArray(),
+  })),
   // hydrate balance chains, evmNetworks, tokens and tokenRates
-  {
-    chains,
-    evmNetworks,
-    tokens,
-    tokenRates
-  }), [balanceModules, addressesByToken, chains, evmNetworks, tokens, tokenRates]);
-
-  // debounce every 100ms to prevent hammering UI with updates
-  const [debouncedBalances, setDebouncedBalances] = useState(balances);
-  useDebounce(() => balances && setDebouncedBalances(balances), 100, [balances]);
-  return debouncedBalances;
+  hydrate), [balances, hydrate, balanceModules, addressesByToken]);
 }
 
-// TODO: Turn into react context
-const subscriptions = {};
+/**
+ * Given a collection of `Balances`, this hook returns a `BalancesStatus` summary for the collection.
+ *
+ * @param balances The collection of balances to get the status from.
+ * @returns An instance of `BalancesStatus` which represents the status of the balances collection.
 
-// This hook is responsible for allowing us to call useBalances
-// from multiple components, without setting up unnecessary
-// balance subscriptions
-function useBalancesSubscriptions(
-// TODO: Make this array of BalanceModules more type-safe
-balanceModules, chaindataProvider, addressesByToken, options = {}) {
-  // const subscriptions = useRef<
-  //   Record<string, { unsub: Promise<() => void>; refcount: number; generation: number }>
-  // >({})
-
-  const addSubscription = (key, balanceModule, chainConnectors, chaindataProvider, addressesByToken) => {
-    // create subscription if it doesn't already exist
-    if (!subscriptions[key] || subscriptions[key].refcount === 0) {
-      const generation = ((subscriptions[key]?.generation || 0) + 1) % Number.MAX_SAFE_INTEGER;
-      const unsub = balances(balanceModule, chainConnectors, chaindataProvider, addressesByToken, (error, balances) => {
-        if (error) return log.error(`Failed to fetch ${balanceModule.type} balances`, error);
-        if (!balances) return;
-
-        // ignore balances from old subscriptions which are still in the process of unsubscribing
-        if (subscriptions[key].generation !== generation) return;
-        const putBalances = Object.entries(balances.toJSON()).map(([id, balance]) => ({
-          id,
-          ...balance
-        }));
-        db.transaction("rw", db.balances, async () => await db.balances.bulkPut(putBalances));
-      });
-      subscriptions[key] = {
-        unsub,
-        refcount: 0,
-        generation
-      };
-    }
+ */
+const useBalancesStatus = balances => useMemo(() => {
+  // stale
+  const staleChains = getStaleChains(balances);
+  if (staleChains.length > 0) return {
+    status: "stale",
+    staleChains
+  };
 
-    // bump up the refcount by 1
-    subscriptions[key].refcount += 1;
+  // fetching
+  const hasCachedBalances = balances.each.some(b => b.status === "cache");
+  if (hasCachedBalances) return {
+    status: "fetching"
   };
-  const removeSubscription = (key, balanceModule, addressesByToken) => {
-    // ignore dead subscriptions
-    if (!subscriptions[key] || subscriptions[key].refcount === 0) return;
-
-    // drop the refcount by one
-    subscriptions[key].refcount -= 1;
-
-    // unsubscribe if refcount is now 0 (nobody wants this subcription anymore)
-    if (subscriptions[key].refcount < 1) {
-      // remove subscription
-      subscriptions[key].unsub.then(unsub => unsub());
-      delete subscriptions[key];
-
-      // set this subscription's balances in the store to status: cache
-      db.transaction("rw", db.balances, async () => await db.balances.filter(balance => {
-        if (balance.source !== balanceModule.type) return false;
-        if (!Object.keys(addressesByToken).includes(balance.tokenId)) return false;
-        if (!addressesByToken[balance.tokenId].includes(balance.address)) return false;
-        return true;
-      }).modify({
-        status: "cache"
-      }));
-    }
+
+  // live
+  return {
+    status: "live"
   };
-  const chainConnector = useChainConnector(chaindataProvider);
-  const chainConnectorEvm = useChainConnectorEvm(chaindataProvider, options);
-  const tokens = useTokens(chaindataProvider);
-  useEffect(() => {
-    if (chainConnector === null) return;
-    if (chainConnectorEvm === null) return;
-    if (chaindataProvider === null) return;
-    if (addressesByToken === null) return;
-    const unsubs = balanceModules.map(balanceModule => {
-      const subscriptionKey = `${balanceModule.type}-${JSON.stringify(addressesByToken)}`;
-
-      // filter out tokens to only include those which this module knows how to fetch balances for
-      const moduleTokenIds = Object.values(tokens).filter(({
-        type
-      }) => type === balanceModule.type).map(({
-        id
-      }) => id);
-      const addressesByModuleToken = Object.fromEntries(Object.entries(addressesByToken).filter(([tokenId]) => moduleTokenIds.includes(tokenId)));
-
-      // add balance subscription for this module
-      addSubscription(subscriptionKey, balanceModule, {
-        substrate: chainConnector,
-        evm: chainConnectorEvm
-      }, chaindataProvider, addressesByModuleToken);
-
-      // return an unsub method, to be called when this effect unmounts
-      return () => removeSubscription(subscriptionKey, balanceModule, addressesByToken);
-    });
-    const unsubAll = () => unsubs.forEach(unsub => unsub());
-    return unsubAll;
-  }, [addressesByToken, balanceModules, chainConnector, chainConnectorEvm, chaindataProvider, tokens]);
-}
+}, [balances]);
+const getStaleChains = balances => [...new Set(balances.sorted.filter(b => b.status === "stale").map(b => b.chain?.name ?? b.chainId ?? "Unknown"))];
 
-// TODO: Allow advanced users of this library to provide their own chain connector
-function useChainConnector(chaindataProvider) {
-  const [chainConnector, setChainConnector] = useState(null);
-  useEffect(() => {
-    if (chaindataProvider === null) return;
-    setChainConnector(new ChainConnector(chaindataProvider));
-  }, [chaindataProvider]);
-  return chainConnector;
-}
-// TODO: Allow advanced users of this library to provide their own chain connector
-function useChainConnectorEvm(chaindataProvider, options = {}) {
-  const [chainConnectorEvm, setChainConnectorEvm] = useState(null);
-  useEffect(() => {
-    if (chaindataProvider === null) return;
-    setChainConnectorEvm(new ChainConnectorEvm(chaindataProvider, {
-      onfinalityApiKey: options.onfinalityApiKey
-    }));
-  }, [chaindataProvider, options.onfinalityApiKey]);
-  return chainConnectorEvm;
-}
+const BalancesProvider = ({
+  balanceModules,
+  onfinalityApiKey,
+  withTestnets,
+  children
+}) => /*#__PURE__*/jsx(WithTestnetsProvider, {
+  withTestnets: withTestnets,
+  children: /*#__PURE__*/jsx(ChaindataProvider, {
+    onfinalityApiKey: onfinalityApiKey,
+    children: /*#__PURE__*/jsx(ChainConnectorsProvider, {
+      onfinalityApiKey: onfinalityApiKey,
+      children: /*#__PURE__*/jsx(AllAddressesProvider, {
+        children: /*#__PURE__*/jsx(BalanceModulesProvider, {
+          balanceModules: balanceModules,
+          children: /*#__PURE__*/jsx(DbCacheProvider, {
+            children: children
+          })
+        })
+      })
+    })
+  })
+});
 
-export { useBalances, useChain, useChaindata, useChains, useEvmNetwork, useEvmNetworks, useToken, useTokenRates, useTokens };
+export { AllAddressesProvider, BalanceModulesProvider, BalancesProvider, ChainConnectorsProvider, ChaindataProvider, DbCacheProvider, WithTestnetsProvider, createMulticastSubscription, getStaleChains, provideContext, useAllAddresses, useBalanceModules, useBalances, useBalancesHydrate, useBalancesStatus, useChain, useChainConnectors, useChaindata, useChains, useDbCache, useDbCacheBalancesSubscription, useDbCacheSubscription, useDbCacheTokenRatesSubscription, useEvmNetwork, useEvmNetworks, useMulticastSubscription, useToken, useTokenRate, useTokenRates, useTokens, useWithTestnets };