@talismn/chain-connectors 0.0.13 → 0.0.15

package/dist/index.d.mts

@@ -0,0 +1,139 @@
+import { ProviderInterface, ProviderInterfaceCallback } from '@polkadot/rpc-provider/types';
+import { DotNetworkId, IChaindataNetworkProvider, DotNetwork, EthNetworkId, IChaindataTokenProvider, EthNetwork, SolNetworkId, SolNetwork } from '@talismn/chaindata-provider';
+import { TalismanConnectionMetaDatabase } from '@talismn/connection-meta';
+import { PublicClient, Account, WalletClient } from 'viem';
+import { Connection } from '@solana/web3.js';
+
+interface IChainConnectorDot {
+    asProvider(chainId: DotNetworkId): ProviderInterface;
+    send<T = unknown>(chainId: DotNetworkId, method: string, params: unknown[], isCacheable?: boolean, extraOptions?: {
+        expectErrors?: boolean;
+    }): Promise<T>;
+    subscribe(chainId: DotNetworkId, subscribeMethod: string, responseMethod: string, params: unknown[], callback: ProviderInterfaceCallback, timeout?: number | false): Promise<(unsubscribeMethod: string) => void>;
+    reset(chainId: DotNetworkId): Promise<void>;
+}
+
+declare class ChainConnectionError extends Error {
+    type: "CHAIN_CONNECTION_ERROR";
+    chainId: string;
+    constructor(chainId: string, options?: ErrorOptions);
+}
+declare class StaleRpcError extends Error {
+    type: "STALE_RPC_ERROR";
+    chainId: string;
+    constructor(chainId: string, options?: ErrorOptions);
+}
+declare class WebsocketAllocationExhaustedError extends Error {
+    type: "WEBSOCKET_ALLOCATION_EXHAUSTED_ERROR";
+    chainId: string;
+    constructor(chainId: string, options?: ErrorOptions);
+}
+/**
+ * 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.
+ */
+declare class ChainConnectorDot implements IChainConnectorDot {
+    #private;
+    constructor(chaindataChainProvider: IChaindataNetworkProvider, connectionMetaDb?: TalismanConnectionMetaDatabase);
+    /**
+     * 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: DotNetworkId): ProviderInterface;
+    send<T = any>(chainId: DotNetworkId, method: string, params: unknown[], isCacheable?: boolean | undefined, extraOptions?: {
+        /**
+         * Set to `true` if this query is speculative, i.e. if on some chains it's expected that it will raise a wasm unreachable error of the form:
+         *
+         *     4003: Client error: Execution failed: Execution aborted due to trap: wasm trap: wasm `unreachable` instruction executed
+         *
+         * By setting expectErrors to true, this method won't pollute the logs with errors we intend to have happen.
+         * An example use case of this is when you plan to catch the wasm unreachable error on chains that don't support the query, and then fall back
+         * to another query or perhaps an empty result.
+         */
+        expectErrors?: boolean;
+    }): Promise<T>;
+    subscribe(chainId: DotNetworkId, subscribeMethod: string, responseMethod: string, params: unknown[], callback: ProviderInterfaceCallback, timeout?: number | false): Promise<(unsubscribeMethod: string) => void>;
+    /**
+     * Kills current websocket if any
+     * Useful after changing rpc order to make sure it's applied for futher requests
+     */
+    reset(chainId: DotNetworkId): Promise<void>;
+    /**
+     * Wait for websocket to be ready, but don't wait forever
+     */
+    private waitForWs;
+    /**
+     * Connect to an RPC via chainId
+     *
+     * The caller must call disconnectChainSocket with the returned SocketUserId once they are finished with it
+     */
+    private connectChainSocket;
+    private disconnectChainSocket;
+    private addSocketUser;
+    private removeSocketUser;
+    /** continues to generate a random number until it finds one which is not present in the exclude list */
+    private getExclusiveRandomId;
+    /** generates a random number */
+    private getRandomId;
+    private getTalismanSub;
+    private updateRpcPriority;
+    private getEndpoints;
+}
+
+declare class ChainConnectorDotStub implements IChainConnectorDot {
+    #private;
+    constructor(network: DotNetwork);
+    asProvider(): ProviderInterface;
+    send<T = unknown>(_chainId: DotNetworkId, method: string, params: unknown[], isCacheable?: boolean): Promise<T>;
+    subscribe(_chainId: DotNetworkId, subscribeMethod: string, responseMethod: string, params: unknown[], callback: ProviderInterfaceCallback, timeout?: number | false): Promise<(unsubscribeMethod: string) => void>;
+    reset(): Promise<void>;
+}
+
+interface IChainConnectorEth {
+    getPublicClientForEvmNetwork: (evmNetworkId: EthNetworkId) => Promise<PublicClient | null>;
+    getWalletClientForEvmNetwork: (evmNetworkId: EthNetworkId, account?: `0x${string}` | Account) => Promise<WalletClient | null>;
+    clearRpcProvidersCache: (evmNetworkId?: EthNetworkId) => void;
+}
+
+declare class ChainConnectorEth implements IChainConnectorEth {
+    #private;
+    constructor(chaindataProvider: IChaindataNetworkProvider & IChaindataTokenProvider);
+    getPublicClientForEvmNetwork(evmNetworkId: EthNetworkId): Promise<PublicClient | null>;
+    getWalletClientForEvmNetwork(evmNetworkId: EthNetworkId, account?: `0x${string}` | Account): Promise<WalletClient | null>;
+    clearRpcProvidersCache(evmNetworkId?: EthNetworkId): void;
+}
+
+declare class ChainConnectorEthStub implements IChainConnectorEth {
+    #private;
+    constructor(network: EthNetwork);
+    getPublicClientForEvmNetwork(): Promise<PublicClient | null>;
+    getWalletClientForEvmNetwork(_networkId: EthNetworkId, account?: `0x${string}` | Account): Promise<WalletClient | null>;
+    clearRpcProvidersCache(): void;
+}
+
+interface IChainConnectorSol {
+    getConnection: (networkId: SolNetworkId) => Promise<Connection>;
+}
+
+declare class ChainConnectorSol implements IChainConnectorSol {
+    #private;
+    constructor(chaindataProvider: IChaindataNetworkProvider & IChaindataTokenProvider);
+    getConnection(networkId: SolNetworkId): Promise<Connection>;
+}
+
+declare class ChainConnectorSolStub implements IChainConnectorSol {
+    #private;
+    constructor(networkOrConnection: Pick<SolNetwork, "id" | "rpcs"> | Connection);
+    getConnection(): Promise<Connection>;
+}
+
+export { ChainConnectionError, ChainConnectorDot, ChainConnectorDotStub, ChainConnectorEth, ChainConnectorEthStub, ChainConnectorSol, ChainConnectorSolStub, type IChainConnectorDot, type IChainConnectorEth, type IChainConnectorSol, StaleRpcError, WebsocketAllocationExhaustedError };

package/dist/index.d.ts

@@ -0,0 +1,139 @@
+import { ProviderInterface, ProviderInterfaceCallback } from '@polkadot/rpc-provider/types';
+import { DotNetworkId, IChaindataNetworkProvider, DotNetwork, EthNetworkId, IChaindataTokenProvider, EthNetwork, SolNetworkId, SolNetwork } from '@talismn/chaindata-provider';
+import { TalismanConnectionMetaDatabase } from '@talismn/connection-meta';
+import { PublicClient, Account, WalletClient } from 'viem';
+import { Connection } from '@solana/web3.js';
+
+interface IChainConnectorDot {
+    asProvider(chainId: DotNetworkId): ProviderInterface;
+    send<T = unknown>(chainId: DotNetworkId, method: string, params: unknown[], isCacheable?: boolean, extraOptions?: {
+        expectErrors?: boolean;
+    }): Promise<T>;
+    subscribe(chainId: DotNetworkId, subscribeMethod: string, responseMethod: string, params: unknown[], callback: ProviderInterfaceCallback, timeout?: number | false): Promise<(unsubscribeMethod: string) => void>;
+    reset(chainId: DotNetworkId): Promise<void>;
+}
+
+declare class ChainConnectionError extends Error {
+    type: "CHAIN_CONNECTION_ERROR";
+    chainId: string;
+    constructor(chainId: string, options?: ErrorOptions);
+}
+declare class StaleRpcError extends Error {
+    type: "STALE_RPC_ERROR";
+    chainId: string;
+    constructor(chainId: string, options?: ErrorOptions);
+}
+declare class WebsocketAllocationExhaustedError extends Error {
+    type: "WEBSOCKET_ALLOCATION_EXHAUSTED_ERROR";
+    chainId: string;
+    constructor(chainId: string, options?: ErrorOptions);
+}
+/**
+ * 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.
+ */
+declare class ChainConnectorDot implements IChainConnectorDot {
+    #private;
+    constructor(chaindataChainProvider: IChaindataNetworkProvider, connectionMetaDb?: TalismanConnectionMetaDatabase);
+    /**
+     * 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: DotNetworkId): ProviderInterface;
+    send<T = any>(chainId: DotNetworkId, method: string, params: unknown[], isCacheable?: boolean | undefined, extraOptions?: {
+        /**
+         * Set to `true` if this query is speculative, i.e. if on some chains it's expected that it will raise a wasm unreachable error of the form:
+         *
+         *     4003: Client error: Execution failed: Execution aborted due to trap: wasm trap: wasm `unreachable` instruction executed
+         *
+         * By setting expectErrors to true, this method won't pollute the logs with errors we intend to have happen.
+         * An example use case of this is when you plan to catch the wasm unreachable error on chains that don't support the query, and then fall back
+         * to another query or perhaps an empty result.
+         */
+        expectErrors?: boolean;
+    }): Promise<T>;
+    subscribe(chainId: DotNetworkId, subscribeMethod: string, responseMethod: string, params: unknown[], callback: ProviderInterfaceCallback, timeout?: number | false): Promise<(unsubscribeMethod: string) => void>;
+    /**
+     * Kills current websocket if any
+     * Useful after changing rpc order to make sure it's applied for futher requests
+     */
+    reset(chainId: DotNetworkId): Promise<void>;
+    /**
+     * Wait for websocket to be ready, but don't wait forever
+     */
+    private waitForWs;
+    /**
+     * Connect to an RPC via chainId
+     *
+     * The caller must call disconnectChainSocket with the returned SocketUserId once they are finished with it
+     */
+    private connectChainSocket;
+    private disconnectChainSocket;
+    private addSocketUser;
+    private removeSocketUser;
+    /** continues to generate a random number until it finds one which is not present in the exclude list */
+    private getExclusiveRandomId;
+    /** generates a random number */
+    private getRandomId;
+    private getTalismanSub;
+    private updateRpcPriority;
+    private getEndpoints;
+}
+
+declare class ChainConnectorDotStub implements IChainConnectorDot {
+    #private;
+    constructor(network: DotNetwork);
+    asProvider(): ProviderInterface;
+    send<T = unknown>(_chainId: DotNetworkId, method: string, params: unknown[], isCacheable?: boolean): Promise<T>;
+    subscribe(_chainId: DotNetworkId, subscribeMethod: string, responseMethod: string, params: unknown[], callback: ProviderInterfaceCallback, timeout?: number | false): Promise<(unsubscribeMethod: string) => void>;
+    reset(): Promise<void>;
+}
+
+interface IChainConnectorEth {
+    getPublicClientForEvmNetwork: (evmNetworkId: EthNetworkId) => Promise<PublicClient | null>;
+    getWalletClientForEvmNetwork: (evmNetworkId: EthNetworkId, account?: `0x${string}` | Account) => Promise<WalletClient | null>;
+    clearRpcProvidersCache: (evmNetworkId?: EthNetworkId) => void;
+}
+
+declare class ChainConnectorEth implements IChainConnectorEth {
+    #private;
+    constructor(chaindataProvider: IChaindataNetworkProvider & IChaindataTokenProvider);
+    getPublicClientForEvmNetwork(evmNetworkId: EthNetworkId): Promise<PublicClient | null>;
+    getWalletClientForEvmNetwork(evmNetworkId: EthNetworkId, account?: `0x${string}` | Account): Promise<WalletClient | null>;
+    clearRpcProvidersCache(evmNetworkId?: EthNetworkId): void;
+}
+
+declare class ChainConnectorEthStub implements IChainConnectorEth {
+    #private;
+    constructor(network: EthNetwork);
+    getPublicClientForEvmNetwork(): Promise<PublicClient | null>;
+    getWalletClientForEvmNetwork(_networkId: EthNetworkId, account?: `0x${string}` | Account): Promise<WalletClient | null>;
+    clearRpcProvidersCache(): void;
+}
+
+interface IChainConnectorSol {
+    getConnection: (networkId: SolNetworkId) => Promise<Connection>;
+}
+
+declare class ChainConnectorSol implements IChainConnectorSol {
+    #private;
+    constructor(chaindataProvider: IChaindataNetworkProvider & IChaindataTokenProvider);
+    getConnection(networkId: SolNetworkId): Promise<Connection>;
+}
+
+declare class ChainConnectorSolStub implements IChainConnectorSol {
+    #private;
+    constructor(networkOrConnection: Pick<SolNetwork, "id" | "rpcs"> | Connection);
+    getConnection(): Promise<Connection>;
+}
+
+export { ChainConnectionError, ChainConnectorDot, ChainConnectorDotStub, ChainConnectorEth, ChainConnectorEthStub, ChainConnectorSol, ChainConnectorSolStub, type IChainConnectorDot, type IChainConnectorEth, type IChainConnectorSol, StaleRpcError, WebsocketAllocationExhaustedError };