@talismn/balances-react 0.3.3 → 0.4.0

package/dist/talismn-balances-react.cjs.prod.js

@@ -2,23 +2,205 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var balances = require('@talismn/balances');
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
 var chainConnector = require('@talismn/chain-connector');
 var chainConnectorEvm = require('@talismn/chain-connector-evm');
+var connectionMeta = require('@talismn/connection-meta');
+var chaindataProviderExtension = require('@talismn/chaindata-provider-extension');
+var balances = require('@talismn/balances');
+var tokenRates = require('@talismn/token-rates');
 var dexieReactHooks = require('dexie-react-hooks');
-var react = require('react');
 var reactUse = require('react-use');
+var md5 = require('blueimp-md5');
 var anylogger = require('anylogger');
-var chaindataProviderExtension = require('@talismn/chaindata-provider-extension');
-var tokenRates = require('@talismn/token-rates');
+var rxjs = require('rxjs');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { 'default': e }; }
 
+var md5__default = /*#__PURE__*/_interopDefault(md5);
 var anylogger__default = /*#__PURE__*/_interopDefault(anylogger);
 
+const provideContext = useProviderContext => {
+  // automatic typing based on our hook's return type
+
+  const Context = /*#__PURE__*/react.createContext({
+    __provideContextInternalDefaultValue: true
+  });
+  const Provider = ({
+    children,
+    ...props
+  }) => {
+    const ctx = useProviderContext(props);
+    return /*#__PURE__*/jsxRuntime.jsx(Context.Provider, {
+      value: ctx,
+      children: children
+    });
+  };
+  const useProvidedContext = () => {
+    const context = react.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 = () => react.useState([]);
+const [AllAddressesProvider, useAllAddresses] = provideContext(useAllAddressesProvider);
+
+function useChaindataProvider(options = {}) {
+  const [onfinalityApiKey, setOnfinalityApiKey] = react.useState(options.onfinalityApiKey);
+
+  // make sure we recreate provider only when the onfinalityApiKey changes
+  react.useEffect(() => {
+    if (options.onfinalityApiKey !== onfinalityApiKey) setOnfinalityApiKey(options.onfinalityApiKey);
+  }, [options.onfinalityApiKey, onfinalityApiKey]);
+  return react.useMemo(() => new chaindataProviderExtension.ChaindataProviderExtension({
+    onfinalityApiKey
+  }), [onfinalityApiKey]);
+}
+const [ChaindataProvider, useChaindata] = provideContext(useChaindataProvider);
+
+function useChainConnectorsProvider(options) {
+  const [onfinalityApiKey, setOnfinalityApiKey] = react.useState(options.onfinalityApiKey);
+
+  // make sure we recreate provider only when the onfinalityApiKey changes
+  react.useEffect(() => {
+    if (options.onfinalityApiKey !== onfinalityApiKey) setOnfinalityApiKey(options.onfinalityApiKey);
+  }, [options.onfinalityApiKey, onfinalityApiKey]);
+
+  // chaindata dependency
+  const chaindata = useChaindata();
+
+  // substrate connector
+  const substrate = react.useMemo(() => new chainConnector.ChainConnector(chaindata, connectionMeta.connectionMetaDb), [chaindata]);
+
+  // evm connector
+  const evm = react.useMemo(() => new chainConnectorEvm.ChainConnectorEvm(chaindata, {
+    onfinalityApiKey
+  }), [chaindata, onfinalityApiKey]);
+  return react.useMemo(() => ({
+    substrate,
+    evm
+  }), [substrate, evm]);
+}
+const [ChainConnectorsProvider, useChainConnectors] = provideContext(useChainConnectorsProvider);
+
+const useBalanceModulesProvider = ({
+  balanceModules
+}) => {
+  const chainConnectors = useChainConnectors();
+  const chaindataProvider = useChaindata();
+  const hydrated = react.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;
+
+  // BEGIN: temp hack to indicate that
+  //          - EVM GLMR is a mirror of substrate GLMR
+  //          - EVM MOVR is a mirror of substrate MOVR
+  //          - EVM DEV is a mirror of substrate DEV
+  //          - EVM ACA is a mirror of substrate ACA
+  const mirrorTokenIds = {
+    "1284-evm-native-glmr": "moonbeam-substrate-native-glmr",
+    "1285-evm-native-movr": "moonriver-substrate-native-movr",
+    "1287-evm-native-dev": "moonbase-alpha-testnet-substrate-native-dev",
+    "787-evm-native-aca": "acala-substrate-native-aca"
+  };
+  Object.entries(mirrorTokenIds).filter(([mirrorToken]) => tokensMap[mirrorToken]).forEach(([mirrorToken, mirrorOf]) => tokensMap[mirrorToken].mirrorOf = mirrorOf);
+  // END: temp hack
+
+  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 = dexieReactHooks.useLiveQuery(() => chaindataProvider?.chains(), [chaindataProvider]);
+  const evmNetworkList = dexieReactHooks.useLiveQuery(() => chaindataProvider?.evmNetworks(), [chaindataProvider]);
+  const tokenList = dexieReactHooks.useLiveQuery(() => chaindataProvider?.tokens(), [chaindataProvider]);
+  const tokenRates$1 = dexieReactHooks.useLiveQuery(() => tokenRates.db.tokenRates.toArray(), []);
+  const rawBalances = dexieReactHooks.useLiveQuery(() => balances.db.balances.toArray(), []);
+  const [dbData, setDbData] = react.useState(DEFAULT_VALUE);
+
+  // debounce every 500ms to prevent hammering UI with updates
+  reactUse.useDebounce(() => {
+    setDbData(consolidateDbCache(chainList, evmNetworkList, tokenList, tokenRates$1, rawBalances));
+  }, 500, [chainList, evmNetworkList, tokenList, rawBalances, tokenRates$1]);
+  const refInitialized = react.useRef(false);
+
+  // force an update as soon as all datasources are fetched, so UI can display data ASAP
+  react.useEffect(() => {
+    if (!refInitialized.current && chainList && evmNetworkList && tokenList && tokenRates$1 && rawBalances) {
+      setDbData(consolidateDbCache(chainList, evmNetworkList, tokenList, tokenRates$1, rawBalances));
+      refInitialized.current = true;
+    }
+  }, [chainList, evmNetworkList, rawBalances, tokenList, tokenRates$1]);
+  return dbData;
+};
+const [DbCacheProvider, useDbCache] = provideContext(useDbCacheProvider);
+
 var packageJson = {
 	name: "@talismn/balances-react",
-	version: "0.3.3",
+	version: "0.4.0",
 	author: "Talisman",
 	homepage: "https://talisman.xyz",
 	license: "UNLICENSED",
@@ -36,7 +218,7 @@ var packageJson = {
 		"/dist"
 	],
 	engines: {
-		node: ">=14"
+		node: ">=18"
 	},
 	scripts: {
 		test: "jest",
@@ -49,11 +231,14 @@ var packageJson = {
 		"@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.0"
 	},
 	devDependencies: {
 		"@talismn/eslint-config": "workspace:^",
@@ -80,139 +265,387 @@ var packageJson = {
 
 var log = anylogger__default["default"](packageJson.name);
 
-// TODO: Allow user to call useChaindata from multiple places
-function useChaindata(options = {}) {
-  const [chaindataProvider, setChaindataProvider] = react.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] = react.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 rxjs.Subject()
+  };
   react.useEffect(() => {
-    const chaindataProvider = new chaindataProviderExtension.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
+  react.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 = react.useMemo(() => createMulticastSubscription(upstream), [upstream]);
+  return subscribe;
+};
+const createMulticastSubscription = upstream => {
+  // Create an upstream observable using the provided function.
+  const upstreamObservable = new rxjs.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 = rxjs.defer(() => upstreamObservable).pipe(rxjs.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 = react.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 = react.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__default["default"](key)}`;
+  }, [tokens]);
+  const subscription = react.useCallback(() => {
+    if (!Object.values(tokens ?? {}).length) return () => {};
+    return subscribeTokenRates(tokens);
+  }, [tokens]);
+  useSharedSubscription(subscriptionKey, subscription);
 }
-function useChains(chaindata) {
-  const [chains, setChains] = react.useState();
-  react.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 = react.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__default["default"](key)}`;
+  }, [allAddresses, balanceModules, chainConnectors, chaindataProvider, tokens]);
+  const subscription = react.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$1 = await tokenRates.fetchTokenRates(tokens);
+      const putTokenRates = Object.entries(tokenRates$1).map(([tokenId, rates]) => ({
+        tokenId,
+        rates
+      }));
+      tokenRates.db.transaction("rw", tokenRates.db.tokenRates, async () => await tokenRates.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 updateDb = balances$1 => {
+    const putBalances = Object.entries(balances$1.toJSON()).map(([id, balance]) => ({
+      id,
+      ...balance
+    }));
+    balances.db.transaction("rw", balances.db.balances, async () => await balances.db.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.balances(balanceModule, addressesByModuleToken, (error, balances$1) => {
+      // log errors
+      if (error) {
+        if (error?.type === "STALE_RPC_ERROR") return balances.db.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$1) return;
+      // ignore balances from old subscriptions which are still in the process of unsubscribing
+      if (unsubscribed) return;
+      updateDb(balances$1);
     });
-  }, [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);
+      });
+      balances.db.balances.where({
+        source: balanceModule.type
+      }).filter(balance => {
+        if (!Object.keys(addressesByModuleToken).includes(balance.tokenId)) return false;
+        if (!addressesByModuleToken[balance.tokenId].includes(balance.address)) return false;
+        return true;
+      }).modify({
+        status: "cache"
+      });
+    };
+  });
+  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] = react.useState();
-  react.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] = react.useState();
-  react.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] = react.useState();
-  react.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] = react.useState();
-  react.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] = react.useState();
-  react.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 = react.useRef(0);
-  const [tokenRates$1, setTokenRates] = react.useState();
-  react.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;
-    tokenRates.fetchTokenRates(tokens).then(tokenRates => {
-      if (thisGeneration !== generation.current) return;
-      setTokenRates(tokenRates);
-    });
-  }, [tokens]);
-  return tokenRates$1 || {};
+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;
+}
+
+const useBalancesHydrate = () => {
+  const {
+    withTestnets
+  } = useWithTestnets();
+  const chains = useChains(withTestnets);
+  const evmNetworks = useEvmNetworks(withTestnets);
+  const tokens = useTokens(withTestnets);
+  const tokenRates = useTokenRates();
+  return react.useMemo(() => ({
+    chains,
+    evmNetworks,
+    tokens,
+    tokenRates
+  }), [chains, evmNetworks, tokens, tokenRates]);
+};
 
-// 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$1 = dexieReactHooks.useLiveQuery(async () => new balances.Balances(await balances.db.balances.filter(balance => {
+function useBalances(addressesByToken) {
+  // keep db data up to date
+  useDbCacheBalancesSubscription();
+  const balanceModules = useBalanceModules();
+  const {
+    balances: balances$1
+  } = useDbCache();
+  const hydrate = useBalancesHydrate();
+  return react.useMemo(() => new balances.Balances(balances$1.filter(balance => {
     // check that this balance is included in our queried balance modules
     if (!balanceModules.map(({
       type
@@ -229,144 +662,91 @@ 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] = react.useState(balances$1);
-  reactUse.useDebounce(() => balances$1 && setDebouncedBalances(balances$1), 100, [balances$1]);
-  return debouncedBalances;
+  hydrate), [balances$1, 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.
+ * @param isLoadingLocks Because the wallet currently fetches locks outside of the balances api, this param can be used to indicate that the locks are still loading, even if the `Balances` collection is not.
+ * @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.balances(balanceModule, chainConnectors, chaindataProvider, addressesByToken, (error, balances$1) => {
-        if (error) return log.error(`Failed to fetch ${balanceModule.type} balances`, error);
-        if (!balances$1) 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$1.toJSON()).map(([id, balance]) => ({
-          id,
-          ...balance
-        }));
-        balances.db.transaction("rw", balances.db.balances, async () => await balances.db.balances.bulkPut(putBalances));
-      });
-      subscriptions[key] = {
-        unsub,
-        refcount: 0,
-        generation
-      };
-    }
+ */
+const useBalancesStatus = (balances, isLoadingLocks) => react.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 || isLoadingLocks) 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
-      balances.db.transaction("rw", balances.db.balances, async () => await balances.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);
-  react.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, isLoadingLocks]);
+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$1, setChainConnector] = react.useState(null);
-  react.useEffect(() => {
-    if (chaindataProvider === null) return;
-    setChainConnector(new chainConnector.ChainConnector(chaindataProvider));
-  }, [chaindataProvider]);
-  return chainConnector$1;
-}
-// TODO: Allow advanced users of this library to provide their own chain connector
-function useChainConnectorEvm(chaindataProvider, options = {}) {
-  const [chainConnectorEvm$1, setChainConnectorEvm] = react.useState(null);
-  react.useEffect(() => {
-    if (chaindataProvider === null) return;
-    setChainConnectorEvm(new chainConnectorEvm.ChainConnectorEvm(chaindataProvider, {
-      onfinalityApiKey: options.onfinalityApiKey
-    }));
-  }, [chaindataProvider, options.onfinalityApiKey]);
-  return chainConnectorEvm$1;
-}
+const BalancesProvider = ({
+  balanceModules,
+  onfinalityApiKey,
+  withTestnets,
+  children
+}) => /*#__PURE__*/jsxRuntime.jsx(WithTestnetsProvider, {
+  withTestnets: withTestnets,
+  children: /*#__PURE__*/jsxRuntime.jsx(ChaindataProvider, {
+    onfinalityApiKey: onfinalityApiKey,
+    children: /*#__PURE__*/jsxRuntime.jsx(ChainConnectorsProvider, {
+      onfinalityApiKey: onfinalityApiKey,
+      children: /*#__PURE__*/jsxRuntime.jsx(AllAddressesProvider, {
+        children: /*#__PURE__*/jsxRuntime.jsx(BalanceModulesProvider, {
+          balanceModules: balanceModules,
+          children: /*#__PURE__*/jsxRuntime.jsx(DbCacheProvider, {
+            children: children
+          })
+        })
+      })
+    })
+  })
+});
 
+exports.AllAddressesProvider = AllAddressesProvider;
+exports.BalanceModulesProvider = BalanceModulesProvider;
+exports.BalancesProvider = BalancesProvider;
+exports.ChainConnectorsProvider = ChainConnectorsProvider;
+exports.ChaindataProvider = ChaindataProvider;
+exports.DbCacheProvider = DbCacheProvider;
+exports.WithTestnetsProvider = WithTestnetsProvider;
+exports.createMulticastSubscription = createMulticastSubscription;
+exports.getStaleChains = getStaleChains;
+exports.provideContext = provideContext;
+exports.useAllAddresses = useAllAddresses;
+exports.useBalanceModules = useBalanceModules;
 exports.useBalances = useBalances;
+exports.useBalancesHydrate = useBalancesHydrate;
+exports.useBalancesStatus = useBalancesStatus;
 exports.useChain = useChain;
+exports.useChainConnectors = useChainConnectors;
 exports.useChaindata = useChaindata;
 exports.useChains = useChains;
+exports.useDbCache = useDbCache;
+exports.useDbCacheBalancesSubscription = useDbCacheBalancesSubscription;
+exports.useDbCacheSubscription = useDbCacheSubscription;
+exports.useDbCacheTokenRatesSubscription = useDbCacheTokenRatesSubscription;
 exports.useEvmNetwork = useEvmNetwork;
 exports.useEvmNetworks = useEvmNetworks;
+exports.useMulticastSubscription = useMulticastSubscription;
 exports.useToken = useToken;
+exports.useTokenRate = useTokenRate;
 exports.useTokenRates = useTokenRates;
 exports.useTokens = useTokens;
+exports.useWithTestnets = useWithTestnets;