@broxus/tvm-connect

TVM Connect

Create a connection to Nekoton-based wallets and dApps

Usage

Installation

To apply this component, install it with npm using following command:

npm install @broxus/tvm-connect

or using yarn:

yarn add @broxus/tvm-connect

Requirements

In general it works great with our UIkit package. If you use this package you don't need to worry about the details.

Minimum requirements

If you are only going to use stores, you should install a few required packages

npm i everscale-inpage-provider everscale-standalone-client mobx

or using yarn:

yarn add everscale-inpage-provider everscale-standalone-client mobx

Full requirements

If you would like to use stores and included react components, you need to install a few more packages

npm i everscale-inpage-provider everscale-standalone-client mobx mobx-react-lite react-intl

or using yarn:

yarn add everscale-inpage-provider everscale-standalone-client mobx-react-lite react-intl

TvmWalletService

The Wallet Service is a key part of this module. It accepts a number of settings and parameters when created and has a convenient interface for working with a connected wallet. It works with wallets whose providers and standalone RPC connections are based on everscale-inpage-provider and everscale-standalone-client.

import { EverWallet, TvmWalletService } from '@broxus/tvm-connect'

const walletService = new TvmWalletService({
    defaultNetworkId: 42,
    networks: [
        {
            chainId: '42',
            currency: {
                decimals: 9,
                icon: '/assets/icons/EVER.svg',
                name: 'Native currency',
                symbol: 'EVER',
                wrappedCurrencyAddress: new AddressLiteral( '0:a49cd4e158a9a15555e624759e2e4e766d22600b7800d891e46f9291f044a93d'), // WEVER
            },
            explorer: {
                accountsSubPath: 'accounts',
                baseUrl: 'https://everscan.io',
                title: 'EVER Scan',
                transactionsSubPath: 'transactions',
            },
            id: 'tvm-42',
            name: 'Everscale',
            rpcUrl: 'https://jrpc.everwallet.net',
            shortName: 'Everscale',
            type: 'tvm',
        },
    ],
    providerId: 'EverWallet', // TvmWalletProviderConfig['id']
    providers: [
        {
            connector: new EverWallet(),
            id: 'EverWallet',
            info: {
                description: 'Premier wallet for the Everscale',
                icon: '/assets/icons/EverWallet.svg',
                links: {
                    android: 'https://play.google.com/store/apps/details?id=com.broxus.crystal.app',
                    chromeExtension: 'https://chrome.google.com/webstore/detail/ever-wallet/cgeeodpfagjceefieflmdfphplkenlfk',
                    firefoxExtension: 'https://addons.mozilla.org/en-GB/firefox/addon/ever-wallet/',
                    homepage: 'https://everwallet.net/',
                    ios: 'https://apps.apple.com/us/app/ever-wallet-everscale/id1581310780',
                },
                name: 'Ever Wallet',
            },
        },
    ],
})

await walletService.connect()

This is library/framework agnostic component. So, you can use it anywhere.

Using with React

First at all, you should wrap entire your app with TvmWalletServiceProvider to share TvmWalletService through all your app components.

import { TvmConnector, TvmWalletServiceProvider } from '@broxus/tvm-connect'
import * as React from 'react'
import * as ReactDOM from 'react-dom'
import { IntlProvider } from 'react-intl'

function App(): JSX.Element {
    return (
        <IntlProvider>
            <TvmWalletServiceProvider>
                ...
                <TvmConnector />
                ...
            </TvmWalletServiceProvider>
        </IntlProvider>
    )
}

ReactDOM.render(<App />, document.body)

Custom service

You may use TvmWalletService to create your own service with provider and connection.

import { TvmWalletService } from '@broxus/tvm-connect'

let service: TvmWalletService

export function useTvmWallet(): TvmWalletService {
    if (service === undefined) {
        service = new TvmWalletService({
            defaultNetworkId: number, // (optional) default is 42 (Everscale Mainnet); 1000 for Venom Testnet
            minWalletVersion: string, // (optional) version of the wallet that supports sendDelayedMessage
            networks: TvmNetworkConfig[], // (optional) supported networks configurations
            providerId: string, // (optional) default is 'ever'
            providers: TvmWalletProviderConfig[], // (optional) providers config
        })
    }
    return service
}

// Pass custom wallet to service provider
function App(): JSX.Element {
    const wallet = useTvmWallet()
    return (
        <IntlProvider>
            <TvmWalletServiceProvider wallet={wallet}>
            ...
                <TvmConnector />
            ...
            </TvmWalletServiceProvider>
        </IntlProvider>
    )
}

Network configuration

Below you can see a models of the network configuration, native currency and explorer config.

interface NativeCurrency<T = Address> {
    balance?: string
    decimals: number
    icon?: string
    name?: string
    symbol: string
    wrappedCurrencyAddress?: T
}


interface TvmNetworkConfig {
    badge?: string
    chainId: string
    currency: NativeCurrency<Address>
    disabled?: boolean
    explorer: NetworkExplorerConfig
    icon?: string
    id: string
    name: string
    rpcUrl: string
    shortName: string
    tokensListUri?: string
    tokenType?: string
    type: 'tvm'
}

interface NetworkExplorerConfig {
    accountsSubPath?: string | null
    baseUrl: string
    title: string
    tokensSubPath?: string
    transactionsSubPath?: string | null
}

Provider configuration

To use more providers (wallets) and their connections, you can configure these providers with the providers option that can be passed when instantiating the TvmWalletService.

interface TvmWalletProviderConfig {
    connector: NekotonConnector
    info: {
        description?: string
        icon?: string
        links?: TvmProviderPlatformLinks & { homepage?: string }
        name: string
    }
    id: string
    isRecent?: boolean
    minVersion?: string
}

export type TvmProviderAvailablePlatforms = 'ios' | 'android' | 'chromeExtension' | 'firefoxExtension'

export type TvmProviderPlatformLinks = Partial<Record<TvmProviderAvailablePlatforms, string>>

Styling

If you are using our UIkit package it will it automatically adapts to your interface colors.

Otherwise, you can import standalone CSS

import '~@broxus/tvm-connect/style.min.css'

Below you can find all supported CSS variables and their defaults

/* Connector */
--tvm-connect-dropdown-trigger-horizontal-padding: var(--global-small-gutter, 8px);
--tvm-connect-dropdown-trigger-vertical-padding: 0;
--tvm-connect-dropdown-background: var(--dropdown-background, #fff);
--tvm-connect-dropdown-border-radius: var(--dropdown-border-radius, 5px);
--tvm-connect-dropdown-box-shadow: 0 8px 32px 0 rgb(63 74 111 / 12%), 0 1px 4px 0 rgb(63 74 111 / 8%);
--tvm-connect-dropdown-color: var(--dropdown-color, #333);
--tvm-connect-dropdown-link-color: var(--dropdown-color, #0af);

/* Providers list buttons */
--tvm-connect-provider-button-border-width: 2px;
--tvm-connect-provider-button-border-style: solid;
--tvm-connect-provider-button-border: transparent;
--tvm-connect-provider-button-hover-border: var(--global-primary-border, transparent);

/* Modal */
--tvm-connect-modal-content-background: var(--modal-content-background, #fff);
--tvm-connect-modal-content-border-radius: 12px;
--tvm-connect-modal-content-box-shadow: 0 8px 32px 0 rgb(63 74 111 / 12%), 0 1px 4px 0 rgb(63 74 111 / 8%);
--tvm-connect-modal-content-color: var(--base-body-color, #383838);
--tvm-connect-modal-content-padding-horizontal: 18px;
--tvm-connect-modal-content-padding-vertical: var(--tvm-connect-modal-content-padding-horizontal);
--tvm-connect-modal-header-padding-horizontal: 0;
--tvm-connect-modal-header-padding-vertical: var(--tvm-connect-modal-content-padding-vertical);
--tvm-connect-modal-title-color: var(--base-heading-color, #383838);
--tvm-connect-modal-title-font-size: var(--modal-title-font-size, 18px);
--tvm-connect-modal-title-font-weight: 500;
--tvm-connect-modal-title-line-height: var(--modal-title-line-height, 22px);
--tvm-connect-modal-body-padding-horizontal: 0;
--tvm-connect-modal-body-padding-vertical: var(--tvm-connect-modal-content-padding-vertical);
--tvm-connect-modal-footer-padding-horizontal: 0;
--tvm-connect-modal-footer-padding-vertical: var(--tvm-connect-modal-content-padding-vertical);

/* Drawer */
--tvm-connect-drawer-content-background: var(--drawer-content-background, #fff);
--tvm-connect-drawer-content-border-radius: 16px;
--tvm-connect-drawer-content-box-shadow: 0 8px 32px 0 rgb(63 74 111 / 12%), 0 1px 4px 0 rgb(63 74 111 / 8%);
--tvm-connect-drawer-content-color: var(--base-body-color, #383838);
--tvm-connect-drawer-content-padding-horizontal: 24px;
--tvm-connect-drawer-content-padding-vertical: var(--tvm-connect-drawer-content-padding-horizontal);
--tvm-connect-drawer-header-padding-horizontal: 0;
--tvm-connect-drawer-header-padding-vertical: var(--tvm-connect-drawer-content-padding-vertical);
--tvm-connect-drawer-title-color: var(--base-heading-color, #383838);
--tvm-connect-drawer-title-font-size: var(--drawer-title-font-size, 24px);
--tvm-connect-drawer-title-font-weight: 500;
--tvm-connect-drawer-title-line-height: var(--drawer-title-line-height, 28px);
--tvm-connect-drawer-body-padding-horizontal: 0;
--tvm-connect-drawer-body-padding-vertical: var(--tvm-connect-drawer-content-padding-vertical);
--tvm-connect-drawer-footer-padding-horizontal: 0;
--tvm-connect-drawer-footer-padding-vertical: var(--tvm-connect-drawer-content-padding-vertical);

/* Connection approve popup stage */
--tvm-connect-connection-request-button-border-width: 2px;
--tvm-connect-connection-request-button-border-style: solid;
--tvm-connect-connection-request-button-border: transparent;
--tvm-connect-connection-request-button-hover-border: var(--global-border, transparent);