@talismn/chain-connectors 0.0.0

package/dist/talismn-chain-connectors.esm.js

@@ -0,0 +1,1202 @@
+import { throwAfter, Deferred, sleep, isTruthy } from '@talismn/util';
+import anylogger from 'anylogger';
+import { RpcCoder } from '@polkadot/rpc-provider/coder';
+import { getWSErrorString } from '@polkadot/rpc-provider/ws/errors';
+import { isChildClass, isUndefined, isNull, objectSpread } from '@polkadot/util';
+import { xglobal } from '@polkadot/x-global';
+import { WebSocket } from '@polkadot/x-ws';
+import EventEmitter from 'eventemitter3';
+import { WsProvider } from '@polkadot/rpc-provider';
+import { fallback, http, createPublicClient, createWalletClient } from 'viem';
+import { fromPairs, toPairs, camelCase } from 'lodash-es';
+import * as chains from 'viem/chains';
+import { Connection } from '@solana/web3.js';
+
+var packageJson = {
+	name: "@talismn/chain-connectors"};
+
+var log = anylogger(packageJson.name);
+
+const twoSecondsMs = 2 * 1000;
+const twoMinutesMs = 2 * 60 * 1000;
+class ExponentialBackoff {
+  #minInterval;
+  #maxInterval;
+  #nextInterval = 0;
+  #active = true;
+  constructor(maxIntervalMs = twoMinutesMs, minIntervalMs = twoSecondsMs) {
+    this.#minInterval = minIntervalMs;
+    this.#maxInterval = maxIntervalMs;
+    this.reset();
+  }
+  enable() {
+    this.#active = true;
+  }
+  disable() {
+    this.#active = false;
+  }
+  increase() {
+    if (this.#nextInterval === 0) this.#nextInterval = 1;
+    this.#nextInterval = this.#capMax(this.#capMin(this.#nextInterval * 2));
+  }
+  decrease() {
+    this.#nextInterval = this.#capMax(this.#capMin(this.#nextInterval / 2));
+  }
+  reset() {
+    this.#nextInterval = this.#minInterval;
+  }
+  resetTo(nextInterval) {
+    this.#nextInterval = this.#capMax(this.#capMin(nextInterval));
+  }
+  resetToMax() {
+    this.#nextInterval = this.#maxInterval;
+  }
+  get isActive() {
+    return this.#active;
+  }
+  get next() {
+    return this.#nextInterval;
+  }
+  get isMin() {
+    return this.#nextInterval === this.#minInterval;
+  }
+  get isMax() {
+    return this.#nextInterval === this.#maxInterval;
+  }
+  #capMin(value) {
+    return Math.max(this.#minInterval, value);
+  }
+  #capMax(value) {
+    return Math.min(this.#maxInterval, value);
+  }
+}
+
+// to account for new requirement for generic arg in this type https://github.com/polkadot-js/api/commit/f4c2b150d3d69d43c56699613666b96dd0a763f4#diff-f87c17bc7fae027ec6d43bac5fc089614d9fa097f466aa2be333b44cee81f0fd
+// TODO incrementally replace 'unknown' with proper types where possible
+
+const ALIASES = {
+  chain_finalisedHead: "chain_finalizedHead",
+  chain_subscribeFinalisedHeads: "chain_subscribeFinalizedHeads",
+  chain_unsubscribeFinalisedHeads: "chain_unsubscribeFinalizedHeads"
+};
+const DEFAULT_TIMEOUT_MS = 60 * 1000;
+const TIMEOUT_INTERVAL = 5_000;
+function eraseRecord(record, cb) {
+  Object.keys(record).forEach(key => {
+    if (cb) {
+      cb(record[key]);
+    }
+    delete record[key];
+  });
+}
+
+/**
+ * # @talismn/chain-connector/Websocket
+ *
+ * @name Websocket
+ *
+ * @description The WebSocket Provider allows sending requests using WebSocket to a WebSocket RPC server TCP port. Unlike the [[HttpProvider]], it does support subscriptions and allows listening to events such as new blocks or balance changes.
+ *
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { Websocket } from '@talismn/chain-connector';
+ *
+ * const provider = new Websocket('ws://127.0.0.1:9944');
+ * ```
+ *
+ * @see [[HttpProvider]]
+ */
+class Websocket {
+  #coder;
+  #endpoints;
+  #headers;
+  #eventemitter;
+  #handlers = {};
+  #isReadyPromise;
+  #waitingForId = {};
+  #autoConnectBackoff;
+  #endpointIndex;
+  #endpointsTriedSinceLastConnection = 0;
+  #isConnected = false;
+  #subscriptions = {};
+  #timeoutId = null;
+  #websocket;
+  #timeout;
+
+  /**
+   * @param {string | string[]}  endpoint    The endpoint url. Usually `ws://ip:9944` or `wss://ip:9944`, may provide an array of endpoint strings.
+   * @param {Record<string, string>} headers The headers provided to the underlying WebSocket
+   * @param {number} [timeout] Custom timeout value used per request . Defaults to `DEFAULT_TIMEOUT_MS`
+   */
+  constructor(endpoint, headers = {}, timeout, nextBackoffInterval) {
+    const endpoints = Array.isArray(endpoint) ? endpoint : [endpoint];
+    if (endpoints.length === 0) {
+      throw new Error("Websocket requires at least one Endpoint");
+    }
+    endpoints.forEach(endpoint => {
+      if (!/^(wss|ws):\/\//.test(endpoint)) {
+        throw new Error(`Endpoint should start with 'ws://', received '${endpoint}'`);
+      }
+    });
+    this.#eventemitter = new EventEmitter();
+    this.#autoConnectBackoff = new ExponentialBackoff();
+    if (nextBackoffInterval) this.#autoConnectBackoff.resetTo(nextBackoffInterval);
+    this.#coder = new RpcCoder();
+    this.#endpointIndex = -1;
+    this.#endpoints = endpoints;
+    this.#headers = headers;
+    this.#websocket = null;
+    this.#timeout = timeout || DEFAULT_TIMEOUT_MS;
+    if (this.#autoConnectBackoff.isActive) {
+      this.connectWithRetry().catch(() => {
+        // does not throw
+      });
+    }
+    this.#isReadyPromise = new Promise(resolve => {
+      this.#eventemitter.once("connected", () => {
+        resolve(this);
+      });
+    });
+  }
+
+  /**
+   * @summary `true` when this provider supports subscriptions
+   */
+  get hasSubscriptions() {
+    return true;
+  }
+
+  /**
+   * @summary `true` when this provider supports clone()
+   */
+  get isClonable() {
+    return true;
+  }
+
+  /**
+   * @summary Whether the node is connected or not.
+   * @return {boolean} true if connected
+   */
+  get isConnected() {
+    return this.#isConnected;
+  }
+
+  /**
+   * @description Promise that resolves the first time we are connected and loaded
+   */
+  get isReady() {
+    return this.#isReadyPromise;
+  }
+  get endpoint() {
+    return this.#endpoints[this.#endpointIndex];
+  }
+
+  /**
+   * @description Returns a clone of the object
+   */
+  clone() {
+    return new Websocket(this.#endpoints);
+  }
+  selectEndpointIndex(endpoints) {
+    this.#endpointsTriedSinceLastConnection += 1;
+    return (this.#endpointIndex + 1) % endpoints.length;
+  }
+
+  /**
+   * @summary Manually connect
+   * @description The [[Websocket]] connects automatically by default, however if you decided otherwise, you may
+   * connect manually using this method.
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async connect() {
+    if (this.#websocket) {
+      throw new Error("WebSocket is already connected");
+    }
+    try {
+      this.#endpointIndex = this.selectEndpointIndex(this.#endpoints);
+
+      // the as typeof WebSocket here is Deno-specific - not available on the globalThis
+      this.#websocket = typeof xglobal.WebSocket !== "undefined" && isChildClass(xglobal.WebSocket, WebSocket) ? new WebSocket(this.endpoint) :
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore - WS may be an instance of ws, which supports options
+      new WebSocket(this.endpoint, undefined, {
+        headers: this.#headers
+      });
+      if (this.#websocket) {
+        this.#websocket.onclose = this.#onSocketClose;
+        this.#websocket.onerror = this.#onSocketError;
+        this.#websocket.onmessage = this.#onSocketMessage;
+        this.#websocket.onopen = this.#onSocketOpen;
+      }
+
+      // timeout any handlers that have not had a response
+      this.#timeoutId = setInterval(() => this.#timeoutHandlers(), TIMEOUT_INTERVAL);
+    } catch (error) {
+      log.error(error);
+      this.#emit("error", error);
+      throw error;
+    }
+  }
+
+  /**
+   * @description Connect, never throwing an error, but rather forcing a retry
+   */
+  async connectWithRetry() {
+    if (!this.#autoConnectBackoff.isActive) return;
+    try {
+      await this.connect();
+    } catch (error) {
+      this.scheduleNextRetry();
+    }
+  }
+  scheduleNextRetry() {
+    if (!this.#autoConnectBackoff.isActive) return;
+    const haveTriedAllEndpoints = this.#endpointsTriedSinceLastConnection > 0 && this.#endpointsTriedSinceLastConnection % this.#endpoints.length === 0;
+    setTimeout(() => {
+      this.connectWithRetry().catch(() => {
+        // does not throw
+      });
+    }, haveTriedAllEndpoints ? this.#autoConnectBackoff.next : 0);
+
+    // Increase backoff when we've tried all endpoints
+    if (haveTriedAllEndpoints) this.#autoConnectBackoff.increase();
+
+    // Fire a stale-rpcs event when we've tried all endpoints in the list
+    // but haven't successfully connected to any of them
+    if (haveTriedAllEndpoints) this.#emit("stale-rpcs", {
+      nextBackoffInterval: this.#autoConnectBackoff.next
+    });
+  }
+
+  /**
+   * @description Manually disconnect from the connection, clearing auto-connect logic
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async disconnect() {
+    // switch off autoConnect, we are in manual mode now
+    this.#autoConnectBackoff.disable();
+    try {
+      if (this.#websocket) {
+        // 1000 - Normal closure; the connection successfully completed
+        this.#websocket.close(1000);
+      }
+    } catch (error) {
+      log.error(error);
+      this.#emit("error", error);
+      throw error;
+    }
+  }
+
+  /**
+   * @summary Listens on events after having subscribed using the [[subscribe]] function.
+   * @param  {ProviderInterfaceEmitted} type Event
+   * @param  {ProviderInterfaceEmitCb}  sub  Callback
+   * @return unsubscribe function
+   */
+  on(type, sub) {
+    this.#eventemitter.on(type, sub);
+    return () => {
+      this.#eventemitter.removeListener(type, sub);
+    };
+  }
+
+  /**
+   * @summary Send JSON data using WebSockets to configured HTTP Endpoint or queue.
+   * @param method The RPC methods to execute
+   * @param params Encoded parameters as applicable for the method
+   * @param subscription Subscription details (internally used)
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  send(method, params, /** @deprecated \@talismn/chain-connector doesn't implement a cache */
+  isCacheable, subscription) {
+    const [id, body] = this.#coder.encodeJson(method, params);
+    const resultPromise = this.#send(id, body, method, params, subscription);
+    return resultPromise;
+  }
+  async #send(id, body, method, params, subscription) {
+    return new Promise((resolve, reject) => {
+      try {
+        if (!this.isConnected || this.#websocket === null) {
+          throw new Error("WebSocket is not connected");
+        }
+        const callback = (error, result) => {
+          error ? reject(error) : resolve(result);
+        };
+
+        // log.debug(() => ["calling", method, body])
+
+        this.#handlers[id] = {
+          callback,
+          method,
+          params,
+          start: Date.now(),
+          subscription
+        };
+        this.#websocket.send(body);
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * @name subscribe
+   * @summary Allows subscribing to a specific event.
+   *
+   * @example
+   * <BR>
+   *
+   * ```javascript
+   * const provider = new Websocket('ws://127.0.0.1:9944');
+   * const rpc = new Rpc(provider);
+   *
+   * rpc.state.subscribeStorage([[storage.system.account, <Address>]], (_, values) => {
+   *   console.log(values)
+   * }).then((subscriptionId) => {
+   *   console.log('balance changes subscription id: ', subscriptionId)
+   * })
+   * ```
+   */
+  subscribe(type, method, params, callback) {
+    return this.send(method, params, false, {
+      callback,
+      type
+    });
+  }
+
+  /**
+   * @summary Allows unsubscribing to subscriptions made with [[subscribe]].
+   */
+  async unsubscribe(type, method, id) {
+    const subscription = `${type}::${id}`;
+
+    // FIXME This now could happen with re-subscriptions. The issue is that with a re-sub
+    // the assigned id now does not match what the API user originally received. It has
+    // a slight complication in solving - since we cannot rely on the send id, but rather
+    // need to find the actual subscription id to map it
+    if (isUndefined(this.#subscriptions[subscription])) {
+      // log.debug(() => `Unable to find active subscription=${subscription}`)
+
+      return false;
+    }
+    delete this.#subscriptions[subscription];
+    try {
+      return this.isConnected && !isNull(this.#websocket) ? this.send(method, [id]) : true;
+    } catch (error) {
+      return false;
+    }
+  }
+  #emit = (type, ...args) => {
+    this.#eventemitter.emit(type, ...args);
+  };
+  #onSocketClose = event => {
+    const error = new Error(`disconnected from ${this.endpoint}: ${event.code}:: ${event.reason || getWSErrorString(event.code)}`);
+    if (this.#autoConnectBackoff.isActive) {
+      // 1000 is a normal closure and should not be logged as an error
+      if (event.code !== 1000) log.error(error.message);
+    }
+    this.#isConnected = false;
+    if (this.#websocket) {
+      this.#websocket.onclose = null;
+      this.#websocket.onerror = null;
+      this.#websocket.onmessage = null;
+      this.#websocket.onopen = null;
+      this.#websocket = null;
+    }
+    if (this.#timeoutId) {
+      clearInterval(this.#timeoutId);
+      this.#timeoutId = null;
+    }
+
+    // reject all hanging requests
+    eraseRecord(this.#handlers, h => {
+      try {
+        h.callback(error, undefined);
+      } catch (err) {
+        // does not throw
+        log.error(err);
+      }
+    });
+    eraseRecord(this.#waitingForId);
+    this.#emit("disconnected");
+    this.scheduleNextRetry();
+  };
+  #onSocketError = error => {
+    // log.debug(() => ["socket error", error])
+    this.#emit("error", error);
+  };
+  #onSocketMessage = message => {
+    // log.debug(() => ["received", message.data])
+    try {
+      const response = JSON.parse(message.data);
+      return isUndefined(response.method) ? this.#onSocketMessageResult(response) : this.#onSocketMessageSubscribe(response);
+    } catch (e) {
+      this.#emit("error", new Error("Invalid websocket message received", {
+        cause: e
+      }));
+    }
+  };
+  #onSocketMessageResult = response => {
+    const handler = this.#handlers[response.id];
+    if (!handler) {
+      // log.debug(() => `Unable to find handler for id=${response.id}`)
+
+      return;
+    }
+    try {
+      const {
+        method,
+        params,
+        subscription
+      } = handler;
+      const result = this.#coder.decodeResponse(response);
+
+      // first send the result - in case of subs, we may have an update
+      // immediately if we have some queued results already
+      handler.callback(null, result);
+      if (subscription) {
+        const subId = `${subscription.type}::${result}`;
+        this.#subscriptions[subId] = objectSpread({}, subscription, {
+          method,
+          params
+        });
+
+        // if we have a result waiting for this subscription already
+        if (this.#waitingForId[subId]) {
+          this.#onSocketMessageSubscribe(this.#waitingForId[subId]);
+        }
+      }
+    } catch (error) {
+      handler.callback(error, undefined);
+    }
+    delete this.#handlers[response.id];
+  };
+  #onSocketMessageSubscribe = response => {
+    const method = ALIASES[response.method] || response.method || "invalid";
+    const subId = `${method}::${response.params.subscription}`;
+    const handler = this.#subscriptions[subId];
+    if (!handler) {
+      // store the JSON, we could have out-of-order subid coming in
+      this.#waitingForId[subId] = response;
+
+      // log.debug(() => `Unable to find handler for subscription=${subId}`)
+
+      return;
+    }
+
+    // housekeeping
+    delete this.#waitingForId[subId];
+    try {
+      const result = this.#coder.decodeResponse(response);
+      handler.callback(null, result);
+    } catch (error) {
+      handler.callback(error, undefined);
+    }
+  };
+  #onSocketOpen = () => {
+    if (this.#websocket === null) {
+      throw new Error("WebSocket cannot be null in onOpen");
+    }
+
+    // log.debug(() => ["connected to", this.endpoint])
+
+    this.#isConnected = true;
+    this.#endpointsTriedSinceLastConnection = 0;
+    this.#autoConnectBackoff.reset();
+    this.#resubscribe();
+    this.#emit("connected");
+    return true;
+  };
+  #resubscribe = () => {
+    const subscriptions = this.#subscriptions;
+    this.#subscriptions = {};
+    Promise.all(Object.keys(subscriptions).map(async id => {
+      const {
+        callback,
+        method,
+        params,
+        type
+      } = subscriptions[id];
+
+      // only re-create subscriptions which are not in author (only area where
+      // transactions are created, i.e. submissions such as 'author_submitAndWatchExtrinsic'
+      // are not included (and will not be re-broadcast)
+      if (type.startsWith("author_")) {
+        return;
+      }
+      try {
+        await this.subscribe(type, method, params, callback);
+      } catch (error) {
+        log.error(error);
+      }
+    })).catch(log.error);
+  };
+  #timeoutHandlers = () => {
+    const now = Date.now();
+    const ids = Object.keys(this.#handlers);
+    for (let i = 0; i < ids.length; i++) {
+      const handler = this.#handlers[ids[i]];
+      if (now - handler.start > this.#timeout) {
+        try {
+          handler.callback(new Error(`No response received from RPC endpoint in ${this.#timeout / 1000}s`), undefined);
+        } catch {
+          // ignore
+        }
+        delete this.#handlers[ids[i]];
+      }
+    }
+  };
+}
+
+// errors that require an rpc fallback
+// https://docs.blastapi.io/blast-documentation/things-you-need-to-know/error-reference
+const BAD_RPC_ERRORS = {
+  "-32097": "Rate limit exceeded",
+  "-32098": "Capacity exceeded"
+};
+class ChainConnectionError extends Error {
+  constructor(chainId, options) {
+    super(`Unable to connect to chain ${chainId}`, options);
+    this.type = "CHAIN_CONNECTION_ERROR";
+    this.chainId = chainId;
+  }
+}
+class StaleRpcError extends Error {
+  constructor(chainId, options) {
+    super(`RPCs are stale/unavailable for chain ${chainId}`, options);
+    this.type = "STALE_RPC_ERROR";
+    this.chainId = chainId;
+  }
+}
+class WebsocketAllocationExhaustedError extends Error {
+  constructor(chainId, options) {
+    super(`No websockets are available from the browser pool to connect to chain ${chainId}`, options);
+    this.type = "WEBSOCKET_ALLOCATION_EXHAUSTED_ERROR";
+    this.chainId = chainId;
+  }
+}
+class CallerUnsubscribedError extends Error {
+  constructor(chainId, unsubscribeMethod, options) {
+    super(`Caller unsubscribed from ${chainId}`, options);
+    this.type = "CALLER_UNSUBSCRIBED_ERROR";
+    this.chainId = chainId;
+    this.unsubscribeMethod = unsubscribeMethod;
+  }
+}
+/**
+ * ChainConnector provides an interface similar to WsProvider, but with three points of difference:
+ *
+ * 1. ChainConnector methods all accept a `chainId` instead of an array of RPCs. RPCs are then fetched internally from chaindata.
+ * 2. ChainConnector creates only one `WsProvider` per chain and ensures that all downstream requests to a chain share the one socket connection.
+ * 3. Subscriptions return a callable `unsubscribe` method instead of an id.
+ *
+ * Additionally, when run on the clientside of a dapp where `window.talismanSub` is available, instead of spinning up new websocket
+ * connections this class will forward all requests through to the wallet backend - where another instance of this class will
+ * handle the websocket connections.
+ */
+class ChainConnectorDot {
+  #chaindataChainProvider;
+  #connectionMetaDb;
+  #socketConnections = {};
+  #socketKeepAliveIntervals = {};
+  #socketUsers = {};
+  constructor(chaindataChainProvider, connectionMetaDb) {
+    this.#chaindataChainProvider = chaindataChainProvider;
+    this.#connectionMetaDb = connectionMetaDb;
+    if (this.#connectionMetaDb) {
+      this.#chaindataChainProvider.getNetworkIds("polkadot").then(chainIds => {
+        // tidy up connectionMeta for chains which no longer exist
+        this.#connectionMetaDb?.chainPriorityRpcs.where("id").noneOf(chainIds).delete();
+        this.#connectionMetaDb?.chainBackoffInterval.where("id").noneOf(chainIds).delete();
+      });
+    }
+  }
+
+  /**
+   * Creates a facade over this ChainConnector which conforms to the PJS ProviderInterface
+   * @example // Using a chainConnector as a Provider for an ApiPromise
+   *   const provider = chainConnector.asProvider('polkadot')
+   *   const api = new ApiPromise({ provider })
+   */
+  asProvider(chainId) {
+    const unsubHandler = new Map();
+    const providerFacade = {
+      hasSubscriptions: true,
+      isClonable: false,
+      isConnected: true,
+      clone: () => providerFacade,
+      connect: () => Promise.resolve(),
+      disconnect: () => Promise.resolve(),
+      on: () => () => {},
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      send: async (method, params, isCacheable) => await this.send(chainId, method, params, isCacheable),
+      subscribe: async (type, method, params, cb) => {
+        const unsubscribe = await this.subscribe(chainId, method, type, params, cb);
+        const subscriptionId = this.getExclusiveRandomId([...unsubHandler.keys()].map(Number)).toString();
+        unsubHandler.set(subscriptionId, unsubscribe);
+        return subscriptionId;
+      },
+      unsubscribe: async (_type, unsubscribeMethod, subscriptionId) => {
+        unsubHandler.get(subscriptionId)?.(unsubscribeMethod);
+        unsubHandler.delete(subscriptionId);
+        return true;
+      }
+    };
+    return providerFacade;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async send(chainId, method, params, isCacheable, extraOptions) {
+    const talismanSub = this.getTalismanSub();
+    if (talismanSub !== undefined) {
+      try {
+        const chain = await this.#chaindataChainProvider.getNetworkById(chainId, "polkadot");
+        if (!chain) throw new Error(`Chain ${chainId} not found in store`);
+        const {
+          genesisHash
+        } = chain;
+        if (typeof genesisHash !== "string") throw new Error(`Chain ${chainId} has no genesisHash in store`);
+        return await talismanSub.send(genesisHash, method, params);
+      } catch (error) {
+        log.warn(`Failed to make wallet-proxied send request for chain ${chainId}. Falling back to plain websocket`, error);
+      }
+    }
+    try {
+      // eslint-disable-next-line no-var
+      var [socketUserId, ws] = await this.connectChainSocket(chainId);
+    } catch (error) {
+      throw new StaleRpcError(chainId, {
+        cause: error
+      });
+    }
+    try {
+      // wait for ws to be ready, but don't wait forever
+      const timeout = 15_000; // 15 seconds in milliseconds
+      await this.waitForWs(ws, timeout);
+    } catch (error) {
+      await this.disconnectChainSocket(chainId, socketUserId);
+      throw new ChainConnectionError(chainId, {
+        cause: error
+      });
+    }
+    try {
+      const timeout = 30_000; // throw after 30 seconds if no response
+      // eslint-disable-next-line no-var
+      var response = await Promise.race([ws.send(method, params, isCacheable), throwAfter(timeout, "TIMEOUT")]);
+    } catch (err) {
+      const error = err;
+      if (error?.message === "TIMEOUT") {
+        log.error(`ChainConnector timeout`, {
+          chainId,
+          endpoint: ws.endpoint,
+          error
+        });
+        await this.updateRpcPriority(chainId, ws.endpoint, "last");
+        await this.reset(chainId);
+        throw new Error("Timeout");
+      }
+      const badRpcError = BAD_RPC_ERRORS[error?.code?.toString() ?? ""];
+      if (badRpcError) {
+        log.error(`ChainConnector ${badRpcError}`, {
+          error,
+          chainId,
+          endpoint: ws.endpoint
+        });
+        await this.updateRpcPriority(chainId, ws.endpoint, "last");
+        await this.reset(chainId);
+        throw new Error(badRpcError);
+      }
+      if (!extraOptions?.expectErrors) log.error(`Failed to send ${method} on chain ${chainId}\nparams: ${JSON.stringify(params)}`, {
+        error,
+        endpoint: ws.endpoint
+      });
+      await this.disconnectChainSocket(chainId, socketUserId);
+      throw error;
+    }
+    await this.disconnectChainSocket(chainId, socketUserId);
+    return response;
+  }
+  async subscribe(chainId, subscribeMethod, responseMethod, params, callback, timeout = 30_000 // 30 seconds in milliseconds
+  ) {
+    const talismanSub = this.getTalismanSub();
+    if (talismanSub !== undefined) {
+      try {
+        const chain = await this.#chaindataChainProvider.getNetworkById(chainId, "polkadot");
+        if (!chain) throw new Error(`Chain ${chainId} not found in store`);
+        const {
+          genesisHash
+        } = chain;
+        if (typeof genesisHash !== "string") throw new Error(`Chain ${chainId} has no genesisHash in store`);
+        const subscriptionId = await talismanSub.subscribe(genesisHash, subscribeMethod, responseMethod, params, callback, timeout);
+        return unsubscribeMethod => talismanSub.unsubscribe(subscriptionId, unsubscribeMethod);
+      } catch (error) {
+        log.warn(`Failed to create wallet-proxied subscription for chain ${chainId}. Falling back to plain websocket`, error);
+      }
+    }
+    try {
+      // eslint-disable-next-line no-var
+      var [socketUserId, ws] = await this.connectChainSocket(chainId);
+    } catch (error) {
+      throw new StaleRpcError(chainId, {
+        cause: error
+      });
+    }
+
+    // by using this `Deferred` promise
+    // (a promise which can be resolved or rejected by code outside of the scope of the promise's constructor)
+    // we can queue up our async cleanup on the promise and then immediately return an unsubscribe method to the caller
+    const unsubDeferred = Deferred();
+    // we return this to the caller so that they can let us know when they're no longer interested in this subscription
+    const unsubscribe = unsubscribeMethod => unsubDeferred.reject(new CallerUnsubscribedError(chainId, unsubscribeMethod));
+    // we queue up our work to clean up our subscription when this promise rejects
+    const callerUnsubscribed = unsubDeferred.promise;
+
+    // used to detect when there are no more websockets available from the browser websocket pool
+    // in this scenario, we'll be waiting for ws.isReady until some existing sockets are closed
+    //
+    // while we're waiting, we'll send an error back to the caller so that they can show some useful
+    // info to the user
+    let noMoreSocketsTimeout = undefined
+
+    // create subscription asynchronously so that the caller can unsubscribe without waiting for
+    // the subscription to be created (which can take some time if e.g. the connection can't be established)
+    ;
+    (async () => {
+      // wait for ws to be ready, but don't wait forever
+      // if timeout is number, cancel when timeout is reached (or caller unsubscribes)
+      // if timeout is false, only cancel when the caller unsubscribes
+      let unsubRpcStatus = null;
+      try {
+        const unsubStale = ws.on("stale-rpcs", ({
+          nextBackoffInterval
+        } = {}) => {
+          callback(new StaleRpcError(chainId), null);
+          if (this.#connectionMetaDb && nextBackoffInterval) {
+            const id = chainId;
+            this.#connectionMetaDb.chainBackoffInterval.put({
+              id,
+              interval: nextBackoffInterval
+            }, id);
+          }
+        });
+        const unsubConnected = ws.on("connected", () => {
+          if (this.#connectionMetaDb) this.#connectionMetaDb.chainBackoffInterval.delete(chainId);
+        });
+        unsubRpcStatus = () => {
+          unsubStale();
+          unsubConnected();
+        };
+        noMoreSocketsTimeout = setTimeout(() => callback(new WebsocketAllocationExhaustedError(chainId), null), 30_000 // 30 seconds in ms
+        );
+        if (timeout) await Promise.race([this.waitForWs(ws, timeout), callerUnsubscribed]);else await Promise.race([ws.isReady, callerUnsubscribed]);
+        clearTimeout(noMoreSocketsTimeout);
+      } catch (error) {
+        clearTimeout(noMoreSocketsTimeout);
+        unsubRpcStatus && unsubRpcStatus();
+        await this.disconnectChainSocket(chainId, socketUserId);
+        return;
+      }
+
+      // create subscription on ws
+      // handle the scenarios where the caller unsubscribes before the subscription has been created and:
+      // - the subscriptionId is already set
+      // - the subscriptionId is not set yet, but will be
+      let subscriptionId = null;
+      let disconnected = false;
+      let unsubscribeMethod = undefined;
+      try {
+        await Promise.race([ws.subscribe(responseMethod, subscribeMethod, params, callback).then(id => {
+          if (disconnected) {
+            unsubscribeMethod && ws.unsubscribe(responseMethod, unsubscribeMethod, id);
+          } else subscriptionId = id;
+        }), callerUnsubscribed]);
+      } catch (error) {
+        if (error instanceof CallerUnsubscribedError) unsubscribeMethod = error.unsubscribeMethod;
+        unsubRpcStatus && unsubRpcStatus();
+        disconnected = true;
+        if (subscriptionId !== null && unsubscribeMethod) await ws.unsubscribe(responseMethod, unsubscribeMethod, subscriptionId);
+        await this.disconnectChainSocket(chainId, socketUserId);
+        return;
+      }
+
+      // unsubscribe from ws subscription when the caller has unsubscribed
+      callerUnsubscribed.catch(async error => {
+        let unsubscribeMethod = undefined;
+        if (error instanceof CallerUnsubscribedError) unsubscribeMethod = error.unsubscribeMethod;
+        unsubRpcStatus && unsubRpcStatus();
+        if (subscriptionId !== null && unsubscribeMethod) await ws.unsubscribe(responseMethod, unsubscribeMethod, subscriptionId);
+        await this.disconnectChainSocket(chainId, socketUserId);
+      }).catch(error => log.warn(error));
+    })();
+    return unsubscribe;
+  }
+
+  /**
+   * Kills current websocket if any
+   * Useful after changing rpc order to make sure it's applied for futher requests
+   */
+  async reset(chainId) {
+    log.info("ChainConnector reset", chainId);
+    const ws = this.#socketConnections[chainId];
+    if (!ws) return;
+    try {
+      clearTimeout(this.#socketKeepAliveIntervals[chainId]);
+      delete this.#socketConnections[chainId];
+      delete this.#socketUsers[chainId];
+      await ws.disconnect();
+    } catch (error) {
+      log.warn(`Error occurred reseting socket ${chainId}`, error);
+    }
+  }
+
+  /**
+   * Wait for websocket to be ready, but don't wait forever
+   */
+  async waitForWs(ws, timeout = 30_000 // 30 seconds in milliseconds
+  ) {
+    const timer = timeout ? sleep(timeout).then(() => {
+      throw new Error(`RPC connect timeout reached: ${ws.endpoint}`);
+    }) : false;
+    await Promise.race([ws.isReady, timer].filter(isTruthy));
+  }
+
+  /**
+   * Connect to an RPC via chainId
+   *
+   * The caller must call disconnectChainSocket with the returned SocketUserId once they are finished with it
+   */
+  async connectChainSocket(chainId) {
+    const rpcs = await this.getEndpoints(chainId);
+    const socketUserId = this.addSocketUser(chainId);
+
+    // retrieve next rpc backoff interval from connection meta db (if one exists)
+    let nextBackoffInterval = undefined;
+    if (this.#connectionMetaDb) nextBackoffInterval = (await this.#connectionMetaDb.chainBackoffInterval.get(chainId))?.interval;
+
+    // NOTE: Make sure there are no calls to `await` between this check and the
+    // next step where we assign a `new Websocket` to `this.#socketConnections[chainId]`
+    //
+    // If there is an `await` between these two steps then there will be a race condition introduced.
+    // The result of this race condition will be the unnecessary creation of multiple instances of
+    // `Websocket` per chain, rather than the intended behaviour where every call to send/subscribe
+    // shares a single `Websocket` per chain.
+    if (this.#socketConnections[chainId]) return [socketUserId, this.#socketConnections[chainId]];
+    if (rpcs.length) this.#socketConnections[chainId] = new Websocket(rpcs, undefined, undefined, nextBackoffInterval);else {
+      throw new Error(`No healthy RPCs available for chain ${chainId}`);
+    }
+
+    // on ws connected event, store current rpc as most recently connected rpc
+    if (this.#connectionMetaDb) {
+      this.#socketConnections[chainId].on("connected", () => {
+        if (!this.#connectionMetaDb) return;
+        const id = chainId;
+        const url = this.#socketConnections[chainId]?.endpoint;
+        if (!url) return;
+        this.updateRpcPriority(id, url, "first").catch(err => log.warn(`updateRpcPriority failed`, err));
+      });
+    }
+    (async () => {
+      if (!this.#socketConnections[chainId]) return log.warn(`ignoring ${chainId} rpc ws healthcheck initialization: ws is not defined`);
+      await this.#socketConnections[chainId].isReady;
+      if (this.#socketKeepAliveIntervals[chainId]) clearInterval(this.#socketKeepAliveIntervals[chainId]);
+      const intervalMs = 10_000; // 10,000ms = 10s
+      this.#socketKeepAliveIntervals[chainId] = setInterval(() => {
+        if (!this.#socketConnections[chainId]) return log.warn(`skipping ${chainId} rpc ws healthcheck: ws is not defined`);
+        if (!this.#socketConnections[chainId].isConnected) return log.warn(`skipping ${chainId} rpc ws healthcheck: ws is not connected`);
+        this.#socketConnections[chainId].send("system_health", []).catch(error => log.warn(`Failed keep-alive for socket ${chainId}`, error));
+      }, intervalMs);
+    })();
+    return [socketUserId, this.#socketConnections[chainId]];
+  }
+  async disconnectChainSocket(chainId, socketUserId) {
+    this.removeSocketUser(chainId, socketUserId);
+    if (this.#socketUsers[chainId].length > 0) return;
+    if (!this.#socketConnections[chainId]) return log.warn(`Failed to disconnect socket: socket ${chainId} not found`);
+    try {
+      this.#socketConnections[chainId].disconnect();
+    } catch (error) {
+      log.warn(`Error occurred disconnecting socket ${chainId}`, error);
+    }
+    delete this.#socketConnections[chainId];
+    clearInterval(this.#socketKeepAliveIntervals[chainId]);
+    delete this.#socketKeepAliveIntervals[chainId];
+  }
+  addSocketUser(chainId) {
+    if (!Array.isArray(this.#socketUsers[chainId])) this.#socketUsers[chainId] = [];
+    const socketUserId = this.getExclusiveRandomId(this.#socketUsers[chainId]);
+    this.#socketUsers[chainId].push(socketUserId);
+    return socketUserId;
+  }
+  removeSocketUser(chainId, socketUserId) {
+    const userIndex = this.#socketUsers[chainId].indexOf(socketUserId);
+    if (userIndex === -1) throw new Error(`Can't remove user ${socketUserId} from socket ${chainId}: user not in list ${this.#socketUsers[chainId].join(", ")}`);
+    this.#socketUsers[chainId].splice(userIndex, 1);
+  }
+
+  /** continues to generate a random number until it finds one which is not present in the exclude list */
+  getExclusiveRandomId(exclude = []) {
+    let id = this.getRandomId();
+    while (exclude.includes(id)) {
+      id = this.getRandomId();
+    }
+    return id;
+  }
+  /** generates a random number */
+  getRandomId() {
+    return Math.trunc(Math.random() * Math.pow(10, 8));
+  }
+  getTalismanSub() {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const talismanSub = typeof window !== "undefined" && window.talismanSub;
+
+    /* eslint-disable @typescript-eslint/no-unsafe-function-type */
+    const rpcByGenesisHashSend = talismanSub?.rpcByGenesisHashSend;
+    const rpcByGenesisHashSubscribe = talismanSub?.rpcByGenesisHashSubscribe;
+    const rpcByGenesisHashUnsubscribe = talismanSub?.rpcByGenesisHashUnsubscribe;
+    if (typeof rpcByGenesisHashSend !== "function") return;
+    if (typeof rpcByGenesisHashSubscribe !== "function") return;
+    if (typeof rpcByGenesisHashUnsubscribe !== "function") return;
+    return {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      send: (genesisHash, method, params) => rpcByGenesisHashSend(genesisHash, method, params),
+      subscribe: (genesisHash, subscribeMethod, responseMethod, params, callback, timeout) => rpcByGenesisHashSubscribe(genesisHash, subscribeMethod, responseMethod, params, callback, timeout),
+      unsubscribe: (subscriptionId, unsubscribeMethod) => rpcByGenesisHashUnsubscribe(subscriptionId, unsubscribeMethod)
+    };
+  }
+  async updateRpcPriority(chainId, rpc, priority) {
+    if (!this.#connectionMetaDb) return;
+    const rpcs = await this.getEndpoints(chainId);
+    if (!rpcs.includes(rpc)) throw new Error(`Unknown rpc for chain ${chainId} : ${rpc}`);
+    const urls = rpcs.filter(r => r !== rpc);
+    if (priority === "first") urls.unshift(rpc);
+    if (priority === "last") urls.push(rpc);
+    if (!isEqual(urls, rpcs)) {
+      // order may not change, especially if there is only one
+      await this.#connectionMetaDb.chainPriorityRpcs.put({
+        id: chainId,
+        urls
+      }, chainId);
+    }
+  }
+  async getEndpoints(chainId) {
+    const chain = await this.#chaindataChainProvider.getNetworkById(chainId, "polkadot");
+    if (!chain) throw new Error(`Chain ${chainId} not found in store`);
+    let rpcs = chain.rpcs.concat(); // clone to avoid mutating the original array
+    const priorityRpcs = this.#connectionMetaDb ? await this.#connectionMetaDb.chainPriorityRpcs.get(chainId) : undefined;
+    if (priorityRpcs) {
+      // use existing priority list of rpcs that still exist, and include missing ones
+      rpcs = [...priorityRpcs.urls.filter(rpc => rpcs.includes(rpc)), ...rpcs.filter(rpc => !priorityRpcs.urls.includes(rpc))];
+    }
+    return rpcs;
+  }
+}
+const isEqual = (a, b) => a.length === b.length && a.every((v, i) => v === b[i]);
+
+const AUTO_CONNECT_TIMEOUT = 3_000;
+const TIMEOUT = 10_000;
+class ChainConnectorDotStub {
+  #network;
+  #provider;
+  constructor(network) {
+    this.#network = network;
+    this.#provider = new WsProvider(network.rpcs, AUTO_CONNECT_TIMEOUT, undefined, TIMEOUT);
+  }
+  asProvider() {
+    return this.#provider;
+  }
+  async send(chainId, method, params, isCacheable) {
+    await this.#provider.isReady;
+    return this.#provider.send(method, params, isCacheable);
+  }
+  async subscribe(chainId, subscribeMethod, responseMethod, params, callback, timeout) {
+    await this.#provider.isReady;
+    const subId = await Promise.race([throwAfter(timeout || TIMEOUT, `Subscription timed out after ${timeout}ms`), this.#provider.subscribe(responseMethod, subscribeMethod, params, callback)]);
+    return unsubscribeMethod => {
+      this.#provider.unsubscribe(responseMethod, unsubscribeMethod, subId);
+    };
+  }
+  reset() {
+    throw new Error("ChainConnectorDotStub does not implement reset");
+  }
+}
+
+// viem chains benefit from multicall config & other viem goodies
+const VIEM_CHAINS = Object.keys(chains).reduce((acc, curr) => {
+  const chain = chains[curr];
+  acc[chain.id] = chain;
+  return acc;
+}, {});
+const chainsCache = new Map();
+const clearChainsCache = networkId => {
+  if (networkId) chainsCache.delete(networkId);else chainsCache.clear();
+};
+const getChainFromEvmNetwork = network => {
+  const {
+    symbol,
+    decimals
+  } = network.nativeCurrency;
+  if (!chainsCache.has(network.id)) {
+    const chainRpcs = network.rpcs ?? [];
+    const viemChain = VIEM_CHAINS[Number(network.id)] ?? {};
+    const chain = {
+      ...viemChain,
+      id: Number(network.id),
+      name: network.name ?? `Ethereum Chain ${network.id}`,
+      rpcUrls: {
+        public: {
+          http: chainRpcs
+        },
+        default: {
+          http: chainRpcs
+        }
+      },
+      nativeCurrency: {
+        symbol,
+        decimals,
+        name: symbol
+      },
+      contracts: {
+        ...viemChain.contracts,
+        ...(network.contracts ? fromPairs(toPairs(network.contracts).map(([name, address]) => [camelCase(name), {
+          address
+        }])) : {})
+      }
+    };
+    chainsCache.set(network.id, chain);
+  }
+  return chainsCache.get(network.id);
+};
+
+const getTransportForEvmNetwork = (evmNetwork, options = {}) => {
+  if (!evmNetwork.rpcs?.length) throw new Error("No RPCs found for EVM network");
+  const {
+    batch
+  } = options;
+  return fallback(evmNetwork.rpcs.map(url => http(url, {
+    batch,
+    retryCount: 0
+  })), {
+    retryCount: 0
+  });
+};
+
+const MUTLICALL_BATCH_WAIT = 25;
+const MUTLICALL_BATCH_SIZE = 100;
+const HTTP_BATCH_WAIT = 25;
+const HTTP_BATCH_SIZE_WITH_MULTICALL = 10;
+const HTTP_BATCH_SIZE_WITHOUT_MULTICALL = 30;
+
+// cache to reuse previously created public clients
+const publicClientCache = new Map();
+const clearPublicClientCache = evmNetworkId => {
+  clearChainsCache(evmNetworkId);
+  if (evmNetworkId) publicClientCache.delete(evmNetworkId);else publicClientCache.clear();
+};
+const getEvmNetworkPublicClient = network => {
+  const chain = getChainFromEvmNetwork(network);
+  if (!publicClientCache.has(network.id)) {
+    if (!network.rpcs.length) throw new Error("No RPCs found for Ethereum network");
+    const batch = chain.contracts?.multicall3 ? {
+      multicall: {
+        wait: MUTLICALL_BATCH_WAIT,
+        batchSize: MUTLICALL_BATCH_SIZE
+      }
+    } : undefined;
+    const transportOptions = {
+      batch: {
+        batchSize: chain.contracts?.multicall3 ? HTTP_BATCH_SIZE_WITH_MULTICALL : HTTP_BATCH_SIZE_WITHOUT_MULTICALL,
+        wait: HTTP_BATCH_WAIT
+      }
+    };
+    const transport = getTransportForEvmNetwork(network, transportOptions);
+    publicClientCache.set(network.id, createPublicClient({
+      chain,
+      transport,
+      batch
+    }));
+  }
+  return publicClientCache.get(network.id);
+};
+
+const getEvmNetworkWalletClient = (network, options = {}) => {
+  const chain = getChainFromEvmNetwork(network);
+  const transport = getTransportForEvmNetwork(network);
+  return createWalletClient({
+    chain,
+    transport,
+    account: options.account
+  });
+};
+
+class ChainConnectorEth {
+  #chaindataProvider;
+  constructor(chaindataProvider) {
+    this.#chaindataProvider = chaindataProvider;
+  }
+  async getPublicClientForEvmNetwork(evmNetworkId) {
+    const network = await this.#chaindataProvider.getNetworkById(evmNetworkId, "ethereum");
+    if (!network) return null;
+    return getEvmNetworkPublicClient(network);
+  }
+  async getWalletClientForEvmNetwork(evmNetworkId, account) {
+    const network = await this.#chaindataProvider.getNetworkById(evmNetworkId, "ethereum");
+    if (!network) return null;
+    return getEvmNetworkWalletClient(network, {
+      account
+    });
+  }
+  clearRpcProvidersCache(evmNetworkId) {
+    clearPublicClientCache(evmNetworkId);
+  }
+}
+
+class ChainConnectorEthStub {
+  #network;
+  constructor(network) {
+    this.#network = network;
+  }
+  async getPublicClientForEvmNetwork() {
+    return getEvmNetworkPublicClient(this.#network);
+  }
+  async getWalletClientForEvmNetwork(networkId, account) {
+    return getEvmNetworkWalletClient(this.#network, {
+      account
+    });
+  }
+  clearRpcProvidersCache() {
+    // No-op for stub
+  }
+}
+
+// TODO
+const getSolConnection = (_networkId, _rpcs) => {
+  return new Connection("https://solana-mainnet.g.alchemy.com/v2/FlflUnY6iZ98J9likA0ZdLSMfa6SqMya", {
+    commitment: "confirmed"
+  });
+};
+
+class ChainConnectorSol {
+  #chaindataProvider;
+  constructor(chaindataProvider) {
+    this.#chaindataProvider = chaindataProvider;
+  }
+  async getConnection(networkId) {
+    const network = await this.#chaindataProvider.getNetworkById(networkId, "solana");
+    if (!network) throw new Error(`Network not found: ${networkId}`);
+    return getSolConnection(networkId, network.rpcs);
+  }
+}
+
+class ChainConnectorSolStub {
+  #connection;
+  constructor(network) {
+    this.#connection = getSolConnection(network.id, network.rpcs);
+  }
+  async getConnection() {
+    return this.#connection;
+  }
+}
+
+export { ChainConnectionError, ChainConnectorDot, ChainConnectorDotStub, ChainConnectorEth, ChainConnectorEthStub, ChainConnectorSol, ChainConnectorSolStub, StaleRpcError, WebsocketAllocationExhaustedError };