@broxus/tvm-connect
Version:
TypeScript SDK for connecting to Nekoton-compatible wallets using a unified interface.
371 lines (370 loc) • 13.2 kB
TypeScript
import { type Forceable, type NativeCurrency, type TvmNetworkConfig, AbstractStore } from '@broxus/js-core';
import { type AddNetwork, type Address, type AssetType, type FullContractState, type Network, type ProviderProperties, type Subscriber, ProviderRpcClient } from 'everscale-inpage-provider';
import { type IReactionDisposer } from 'mobx';
import { type ConnectOptions, type DisconnectOptions, type NekotonConnector } from '../core';
import { type TvmWalletProviderConfig, type TvmWalletProviderInfo } from '../types';
export interface TvmConnectServiceCtorParams {
/**
* **Whether to allow unsupported networks.**
*
* That means if the connector will change the network
* to the unsupported one - service will react for this
* and will try to connect to the unsupported network
* for update account state.
*
* @default true
*/
allowUnsupportedNetworks?: boolean;
/**
* **Whether to initialize the connection automatically.**
*
* @example
* ```typescript
* const service = new TvmConnectService({
* autoInit: false,
* providerId: 'SparXWallet',
* providers: [...]
* })
* const sparx = await service.init()
*
* await service.connect()
* ```
* @default true
*/
autoInit?: boolean;
/**
* **Standalone connection parameters (no permissions required).**
*
* @example
* ```typescript
* import { StandaloneClientAdapter, TvmChains } from '@broxus/js-core'
* import { TvmConnectService } from '@broxus/tvm-connect/sdk'
* import { ProviderRpcClient, StaticProviderAdapter } from 'everscale-inpage-provider'
*
* const service = new TvmConnectService({
* connectionParams: {
* // Use factory to recreate connection when network has been changed
* factory: (network) => new ProviderRpcClient({
* provider: new StandaloneClientAdapter({
* connection: network ? network.connectionProperties || {
* data: { endpoint: network.rpcUrl },
* id: Number(network.chainId),
* type: 'proto',
* } : 'mainnetJrpc',
* }),
* }),
* // ... or use your own connection directly from external source
* provider: new StaticProviderAdapter(...),
* },
* defaultNetworkId: TvmChains.EverscaleMainnet,
* networks: [...],
* providerId: 'SparXWallet',
* providers: [...],
* })
*
* await service.connect()
* ```
*
* @param {(network?: TvmNetworkConfig) => ProviderRpcClient} factory - Factory function to
* create a new RPC client
* @param {ProviderProperties['provider']} provider - Custom external Provider properties
* @param {'jrpc' | 'proto'} type - Connection type
*/
connectionParams?: {
factory?: (network?: TvmNetworkConfig) => ProviderRpcClient;
provider?: ProviderProperties['provider'];
};
/**
* **Default network chain id.**
*
* Should be provided if you want to define the default network for the service.
*
* `networks` parameter should be provided to use this feature.
*
* @default TvmChains.EverscaleMainnet
*/
defaultNetworkId?: number;
/**
* **The list of supported networks.**
*
* Should be provided if you want to use the more service features.
*/
networks?: Readonly<TvmNetworkConfig[]>;
/**
* **Provider ID for service initialization (using connectors provided in the `providers`
* parameter).**
*
* `SparXWallet`, `EverWallet`, and `VenomWallet` connectors are supported out of the box.
*/
providerId?: string;
/**
* **The list of supported Providers.**
*
* `SparXWallet`, `EverWallet`, and `VenomWallet` connectors are supported out of the box.
*
* @example
* ```typescript
* import { SparXWallet, TvmConnectService } from '@broxus/tvm-connect/sdk'
*
* const sparxWallet: TvmWalletProviderConfig = {
* connector: new SparXWallet(),
* id: 'SparXWallet',
* info: {
* description: 'Your universal tool for TVM',
* icon: '/assets/icons/SparXWallet.svg', // your own icon
* links: {
* android: 'https://play.google.com/store/apps/details?id=com.broxus.sparx.app',
* chromeExtension:
* 'https://chromewebstore.google.com/detail/sparx-wallet/aijecocmefcagpmbpjcfjjbcclfmobgf',
* homepage: 'https://sparxwallet.com/', ios:
* 'https://apps.apple.com/us/app/sparx-tvm-wallet/id6670219321', name: 'SparX Wallet',
* },
* },
* }
*
* const service = new TvmConnectService({
* defaultNetworkId: TvmChains.EverscaleMainnet,
* networks: [...],
* providerId: 'SparXWallet',
* providers: [sparxWallet],
* })
*
* await service.connect()
* ```
*/
providers?: Readonly<TvmWalletProviderConfig[]>;
/**
* **Storage key for recent connection meta.**
*
* If you want to use the recent connection meta feature, you should provide a storage key
* for it.
*
* @default 'tvm-connect:recent-connection-meta'
* @example
* ```typescript
* const service = new TvmConnectService({
* recentMetaStorageKey: '@{dAppName}/tvmRecentConnectionMeta',
* })
* ```
*
* @see getRecentConnectionMeta
* @see storeRecentConnectionMeta
*/
recentMetaStorageKey?: string;
}
export interface TvmConnectServiceData {
contractState?: FullContractState;
networks: Readonly<TvmNetworkConfig[]>;
providers?: Readonly<TvmWalletProviderConfig[]>;
}
export interface TvmConnectServiceState {
chainId?: number;
isSyncing?: boolean;
providerId?: string;
}
export declare class TvmConnectService extends AbstractStore<TvmConnectServiceData, TvmConnectServiceState> {
protected readonly params?: Readonly<TvmConnectServiceCtorParams> | undefined;
readonly name = "TvmWalletService";
constructor(params?: Readonly<TvmConnectServiceCtorParams> | undefined);
/**
* Returns an instance of the current connector that provides an interface
* to interact with associated provider in the usage environment.
* @returns {NekotonConnector|undefined}
*/
get connector(): NekotonConnector | undefined;
/**
* Initialize the wallet connection manually
* @returns {Promise<ProviderRpcClient | undefined>}
*/
init(): Promise<ProviderRpcClient | undefined>;
/**
* Manually connect to the wallet
* @returns {Promise<void>}
*/
connect(networkIdOParams?: number | AddNetwork, options?: ConnectOptions): Promise<void>;
/**
* Manually disconnect from the wallet
* @param {DisconnectOptions} [options]
* @returns {Promise<void>}
*/
disconnect(options?: DisconnectOptions): Promise<void>;
/**
* Add custom token asset to the TVM Wallet
* @param {Address | string} address
* @param {AssetType} [type]
*/
addAsset(address: Address | string, type?: AssetType): Promise<boolean | undefined>;
/**
* Add new network to the wallet.
* Supported since version `0.3.40` of the `everscale-inpage-provider`
* @param {AddNetwork} network
* @param {boolean} switchNetwork
* @returns {Promise<Network | null>}
*/
addNetwork(network: AddNetwork, switchNetwork?: boolean): Promise<Network | null>;
/**
* Switch to network by the given networkId or network params.
* Supported since version `0.3.40` of the `everscale-inpage-provider`
* @param {number | AddNetwork} networkIdOParams
* @returns {Promise<Network | null>}
*/
switchNetwork(networkIdOParams: number | AddNetwork): Promise<Network | null>;
/**
* Change current account in the wallet.
* @returns {Promise<void>}
*/
changeAccount(): Promise<void>;
/**
* An independent RPC connection that allows you to receive data from the blockchain without
* being able to send transactions.
*
* This connection does not require `accountInteraction` permissions.
* @returns {ProviderRpcClient}
*/
get connection(): ProviderRpcClient;
/**
* A Provider that requires a `basic` and `accountInteraction` permissions for the ability to
* send transactions.
* @returns {ProviderRpcClient|undefined}
*/
get provider(): ProviderRpcClient | undefined;
/**
* Returns computed wallet contract state
* @returns {TvmConnectServiceData["contractState"]}
*/
get contract(): TvmConnectServiceData['contractState'];
/**
* The list of the supported networks
* @returns {TvmConnectServiceData["networks"]}
*/
get networks(): TvmConnectServiceData['networks'];
/**
* The list of the supported providers
* @returns {TvmConnectServiceData["providers"]}
*/
get providers(): TvmConnectServiceData['providers'];
/**
* Returns current network chain id
* @returns {TvmConnectServiceState["chainId"]}
*/
get chainId(): TvmConnectServiceState['chainId'];
/**
* Returns `true` if wallet contract is updating
* @returns {TvmConnectServiceState["isSyncing"]}
*/
get isSyncing(): TvmConnectServiceState['isSyncing'];
/**
* A unique identifier of the connected wallet (provider)
* @returns {TvmConnectServiceState["providerId"]}
*/
get providerId(): TvmConnectServiceState['providerId'];
/**
* Returns computed wallet address value
* @returns {Address|undefined}
*/
get address(): Address | undefined;
/**
* Returns computed wallet normalized balance value
* @returns {FullContractState["balance"]}
*/
get balance(): FullContractState['balance'];
/**
* Returns network native currency
* @returns {NativeCurrency<Address>}
*/
get currency(): Readonly<NativeCurrency<Address>>;
/**
* Whether provider is available.
*
* That means extension is installed and activated, else `false`
* @returns {boolean}
*/
get hasProvider(): boolean;
/**
* Returns `true` if wallet is connected
* @returns {boolean}
*/
get isConnected(): boolean;
/**
* Returns `true` if installed wallet has outdated version
*/
get isOutdated(): boolean;
/**
* Returns `true` if connection to RPC is initialized and connected
* @returns {boolean}
*/
get isReady(): boolean;
/**
* Checks for supported network
* @returns {boolean}
*/
get isUnsupportedNetwork(): boolean;
/**
* Returns current network configuration
* @returns {TvmNetworkConfig|undefined}
*/
get network(): TvmNetworkConfig | undefined;
/**
* Returns details about current connected provider
* @returns {TvmWalletProviderInfo | undefined}
*/
get providerInfo(): TvmWalletProviderInfo | undefined;
/**
* Returns computed account
* @returns {NekotonConnector["account"]}
*/
get account(): NekotonConnector['account'];
/**
* Returns `true` if wallet is connecting
* @returns {NekotonConnector["isConnecting"]}
*/
get isConnecting(): NekotonConnector['isConnecting'];
/**
* Returns `true` if wallet is disconnecting
* @returns {NekotonConnector["isDisconnecting"]}
*/
get isDisconnecting(): NekotonConnector['isDisconnecting'];
/**
* Returns `true` if wallet is initialized
* @returns {NekotonConnector["isInitialized"]}
*/
get isInitialized(): NekotonConnector['isInitialized'];
/**
* Returns `true` if wallet is initializing
* @returns {NekotonConnector["isInitializing"]}
*/
get isInitializing(): NekotonConnector['isInitializing'];
/**
* Synchronizes the contract state of the current account.
*
* If `force` is not set, it will only sync if not already syncing.
*
* @param {Forceable} [options] - Options to control the sync behavior.
* @returns {Promise<void>}
*/
protected syncContractState(options?: Forceable): Promise<void>;
/**
* Initializes the reactive logic for synchronizing the state of the contract and network.
* Sets up disposers for reacting to address changes and network chain ID updates.
*
* @return {Promise<void>}
*/
protected _init(): Promise<void>;
/**
* Subscribe to current account address contract state updates
* and update the local data while updates is coming.
* @returns {Promise<void>}
* @protected
*/
protected _watch(): Promise<void>;
/**
* Unsubscribe from current account address contract state updates.
*
* @returns {Promise<void>}
* @protected
*/
protected _unwatch(): Promise<void>;
protected _accountDisposer: IReactionDisposer | undefined;
protected _contractSubscriber: Subscriber | undefined;
protected _networkDisposer: IReactionDisposer | undefined;
}