Torus EVM Wallet UI Plugin
@web3auth/torus-wallet-connector-plugin
Torus EVM Wallet UI Plugin helps you get the functionalities of the Torus EVM Wallet into your Web3Auth Instance. It helps you use your Web3Auth key in the Torus EVM Wallet, making it easier for your end user to make transactions, add money into their wallet and even use it across different applications using Torus Wallet.
After initialisation, this plugin you a provider from the Torus EVM Wallet, injecting the Torus Wallet UI into your dApp and helping you make the wallet calls directly through it without the need of making your own wallet UI flow.
In this section we'll explore more about how you can use the Torus EVM Wallet UI Plugin for your dApp.
Installation
@web3auth/torus-wallet-connector-plugin
- npm
- Yarn
- pnpm
npm install --save @web3auth/torus-wallet-connector-plugin
yarn add @web3auth/torus-wallet-connector-plugin
pnpm add @web3auth/torus-wallet-connector-plugin
Initialisation
Import the TorusWalletConnectorPlugin
class from @web3auth/torus-wallet-connector-plugin
.
import { TorusWalletConnectorPlugin } from "@web3auth/torus-wallet-connector-plugin";
Assign the TorusWalletConnectorPlugin
class to a variable
After creating your Web3Auth instance, you need to initialise the Torus Wallet UI Plugin and add it to a class for further usage.
const torusPlugin = new TorusWalletConnectorPlugin(options);
This constructor takes an objects with torusWalletOpts
& walletInitOptions
as input.
Arguments
While initializing the plugin, you need to pass on the following parameters to the constructor:
- Table
- Interface
Parameter | Type | Description | Mandatory |
---|---|---|---|
torusWalletOpts? | TorusCtorArgs | Configuration options for Torus Wallet | No |
walletInitOptions | Partial<TorusParams> & Required<Pick<TorusParams, "whiteLabel">> | Parameters to customise your Torus Wallet Embed UI within the application | Yes |
constructor(options: {
torusWalletOpts?: TorusCtorArgs;
walletInitOptions: Partial<TorusParams> & Required<Pick<TorusParams, "whiteLabel">>;
});
torusWalletOpts
torusWalletOpts
is an optional parameter that allows you to pass in the configuration options for Torus Wallet. It takes the TorusCtorArgs
object
as input which contains the following parameters:
- Table
- Interface
TorusCtorArgs
Parameter | Type | Description | Default Value | Mandatory |
---|---|---|---|---|
buttonPosition? | enum - (bottom-left , top-left , bottom-right , top-right ) | Determines where the torus widget is visible on the page. | bottom-left | No |
modalZIndex? | number | Z-index of the modal and iframe | 99999 | No |
buttonSize | number | Size of the widget button | 56 | No |
apiKey? | string | Torus Wallet API Key - Get it from Web3Auth Dashboard | No |
export interface TorusCtorArgs {
/**
* Determines where the torus widget is visible on the page.
* @defaultValue bottom-left
*/
buttonPosition?: BUTTON_POSITION_TYPE;
/**
* Size of the widget button
* @defaultValue 56
*/
buttonSize?: number;
/**
* Z-index of the modal and iframe
* @defaultValue 99999
*/
modalZIndex?: number;
/**
* Api key
* Get yours today at {@link https://developer.tor.us | Dashboard}
*/
apiKey?: string;
}
declare const BUTTON_POSITION: {
readonly BOTTOM_LEFT: "bottom-left";
readonly TOP_LEFT: "top-left";
readonly BOTTOM_RIGHT: "bottom-right";
readonly TOP_RIGHT: "top-right";
};
walletInitOptions
The walletInitOptions
from Torus Wallet is a required parameter that allows you to customise your Torus Wallet Embed Modal UI within the
application. It takes the objet TorusParams
as input which contains multiple parameters mentioned in the
Torus Wallet Documentation.
Out of those mentioned parameters, the following 3 parameters are important for whitelabeling the plugin:
- Table
- Interface
TorusParams
Parameter | Type | Mandatory | Description | Default |
---|---|---|---|---|
whiteLabel | WhiteLabelParams | Yes | Params to enable whitelabelling of torus website and widget. Know more about whitelabeling options for Torus Wallet here. | N/A |
showTorusButton | boolean | No | Determines whether to show/hide torus widget. | true |
useWalletConnect | boolean | No | Setting useWalletConnect to true allows to display wallet connect qr scanner from torus-embed. | false |
export interface TorusParams {
/**
* Torus Network Object
*/
network?: NetworkInterface;
/**
* Build Environment of Torus.
*
* production uses https://app.tor.us,
*
* development uses http://localhost:4050 (expects torus-website to be run locally),
*
* binance uses https://binance.tor.us,
*
* lrc uses https://lrc.tor.us,
*
* beta uses https://beta.tor.us, (currently supports tkey)
*
* testing uses https://testing.tor.us (latest internal build)
* @defaultValue production
*/
buildEnv?: TORUS_BUILD_ENV_TYPE;
/**
* Enables or disables logging.
*
* Defaults to false in prod and true in other environments
*/
enableLogging?: boolean;
/**
* whether to show/hide torus widget.
*
* Defaults to true
* @defaultValue true
*/
showTorusButton?: boolean;
/**
* setting false, hides those verifiers from login modal
* @deprecated
* Please use loginConfig instead
*/
enabledVerifiers?: VerifierStatus;
/**
* Array of login config items. Used to modify the default logins/ add new logins
*/
loginConfig?: LoginConfig;
/**
* Params to enable integrity checks and load specific versions of torus-website
*/
integrity?: IntegrityParams;
/**
* Params to enable whitelabelling of torus website and widget
*/
whiteLabel?: WhiteLabelParams;
/**
* Skips TKey onboarding for new users
*
* Defaults to false
* @defaultValue false
*/
skipTKey?: boolean;
/**
* Setting `useWalletConnect` to true allows to display wallet connect qr scanner from torus-embed.
*
* Defaults to false
* @defaultValue false
*/
useWalletConnect?: boolean;
/**
* Setting mfa level to `default` will present mfa screen to user on every third login
* Setting mfa level to `optional` will present mfa screen to user on every login but user can skip it
* Setting mfa level to `mandatory` will make it mandatory for user to setup mfa after login
* Setting mfa level to`none` will make the user skip the mfa setup screen
*
* Defaults to default
* @defaultValue default
*/
mfaLevel?: "none" | "default" | "optional" | "mandatory";
}
While initializing the plugin, you need to pass on the following parameters to the constructor:
whiteLabel
As you can see, the whiteLabel
parameter is a required parameter within the plugin. This is because this plugin needs you to incorporate basic
whitelabel to avoid showing the Torus Wallet branding on your website.
The whiteLabel
parameter takes WhiteLabelParams
object as input which contains the following parameters:
- Table
- Interface
Parameter | Type | Mandatory | Description | Default |
---|---|---|---|---|
theme | ThemeParams (contains two params, isDark: boolean & colors: Record<string, string> ) | Yes | Params to customise the theme for the wallet embed. You can enable darkMode and use the colours of your choice for the modal. | N/A |
logoDark | string | Yes | Logo to be shown on dark background (dark theme) | N/A |
logoLight | string | Yes | Logo to be shown on light background (light theme) | N/A |
defaultLanguage? | string | No | Language of whitelabel | Order of preference: Whitelabel language > user language (in torus-website) > browser language |
topupHide? | boolean | No | Shows/hides topup option in torus-website/widget. | false |
featuredBillboardHide? | boolean | No | Shows/hides billboard in torus-website. | false |
disclaimerHide? | boolean | No | Shows/hides disclaimers on login page. Only works if special logins are hidden | false |
tncLink? | string | No | Language specific link for terms and conditions on torus-website. Choose between:
| en - English |
privacyPolicy? | string | No | Language specific link for privacy policy on torus-website. | en - English |
contactLink? | string | No | Language specific link for contact links on torus-website. | en - English |
customTranslations? | string | No | Custom translations. | en - English |
interface WhiteLabelParams {
/**
* Whitelabel theme
*/
theme: ThemeParams;
/**
* Language of whitelabel.
*
* order of preference: Whitelabel language \> user language (in torus-website) \> browser language
*/
defaultLanguage?: string;
/**
* Logo Url to be used in light mode (dark logo)
*/
logoDark: string;
/**
* Logo Url to be used in dark mode (light logo)
*/
logoLight: string;
/**
* Shows/hides topup option in torus-website/widget.
* Defaults to false
* @defaultValue false
*/
topupHide?: boolean;
/**
* Shows/hides billboard in torus-website.
* Defaults to false
* @defaultValue false
*/
featuredBillboardHide?: boolean;
/**
* Shows/hides disclaimers on login page. Only works if special logins are hidden
* Defaults to false
* @defaultValue false
*/
disclaimerHide?: boolean;
/**
* Language specific link for terms and conditions on torus-website. See (examples/vue-app) to configure
*/
tncLink?: LocaleLinks<string>;
/**
* Language specific link for privacy policy on torus-website. See (examples/vue-app) to configure
*/
privacyPolicy?: LocaleLinks<string>;
/**
* Language specific link for privacy policy on torus-website. See (examples/vue-app) to configure
*/
contactLink?: LocaleLinks<string>;
/**
* Custom translations. See (examples/vue-app) to configure
*/
customTranslations?: LocaleLinks<unknown>;
}
interface ThemeParams {
/**
* If true, enables dark mode
* Defaults to false
* @defaultValue false
*/
isDark: boolean;
/**
* Colors object to customize colors in torus theme.
*
* Contact us for whitelabel. Example provided in `examples/vue-app`
*/
colors: Record<string, string>;
}
type Record<K extends keyof any, T> = {
[P in K]: T;
};
export interface LocaleLinks<T> {
/**
* Item corresponding to english
*/
en?: T;
/**
* Item corresponding to japanese
*/
ja?: T;
/**
* Item corresponding to korean
*/
ko?: T;
/**
* Item corresponding to german
*/
de?: T;
/**
* Item corresponding to chinese (simplified)
*/
zh?: T;
/**
* Item corresponding to spanish
*/
es?: T;
}
For additional information on the init options for Torus Wallet, please check the Torus Wallet documentation
Add the torusPlugin
class to your Web3Auth instance
After initialising the torusPlugin
, use the addPlugin()
function to your Web3Auth instance, you can use the Torus Wallet UI Plugin for your dApp.
await web3AuthInstance.addPlugin(torusPlugin);
Example
In this example we're adding the TorusWalletConnectorPlugin
with a very basic configuration.
import { TorusWalletConnectorPlugin } from "@web3auth/torus-wallet-connector-plugin";
const torusPlugin = new TorusWalletConnectorPlugin({
torusWalletOpts: {},
walletInitOptions: {
whiteLabel: {
theme: { isDark: true, colors: { primary: "#00a8ff" } },
logoDark: "https://web3auth.io/images/w3a-L-Favicon-1.svg",
logoLight: "https://web3auth.io/images/w3a-D-Favicon-1.svg",
},
useWalletConnect: true,
enableLogging: true,
},
});
await web3auth.addPlugin(torusPlugin);
Using the Torus EVM Wallet Provider
As soon as you add the torusPlugin
class to your Web3Auth instance, you have access to the Torus Wallet Provider. You can use this provider to
access the Torus Wallet UI within your dApp and make RPC calls through that. To use the provider, use the following command:
setWalletProvider((torusPlugin?.proxyProvider as IProvider) || web3auth?.provider);
showWalletConnectScanner()
Shows the Wallet Connect Scanner to connect with dApps having Wallet Connect login option.
Example
import { TorusWalletConnectorPlugin } from "@web3auth/torus-wallet-connector-plugin";
const torusPlugin = new TorusWalletConnectorPlugin({
torusWalletOpts: {},
walletInitOptions: {
whiteLabel: {
theme: { isDark: true, colors: { primary: "#00a8ff" } },
logoDark: "https://web3auth.io/images/w3a-L-Favicon-1.svg",
logoLight: "https://web3auth.io/images/w3a-D-Favicon-1.svg",
},
useWalletConnect: true, // make sure this is enabled before using the showWalletConnectScanner function
enableLogging: true,
},
});
await web3auth.addPlugin(torusPlugin); // add plugin to web3auth instance
await torusPlugin.showWalletConnectScanner();
initiateTopup()
Initiates the Top Up flow with selected provider.
Arguments
- Table
- Interface
Parameter | Type | Description | Mandatory |
---|---|---|---|
provider | PAYMENT_PROVIDER_TYPE ["moonpay" , "wyre" , "rampnetwork" , "xanpool" , "mercuryo" , "transak" , "banxa" ] | Payment Provider name | Yes |
params | PaymentParams | Payment Params object | Yes |
PaymentParams
Parameter | Type | Description | Mandatory |
---|---|---|---|
selectedAddress? | string | Address to send the funds to | No |
selectedCurrency? | string | Default fiat currency for the user to make the payment in | No |
fiatValue? | number | Amount to buy in the selectedCurrency | No |
selectedCryptoCurrency? | string | Cryptocurrency to buy | No |
chainNetwork? | SUPPORTED_PAYMENT_NETWORK_TYPE ["mainnet" , "matic" , "bsc_mainnet" , "avalanche_mainnet" , "xdai" ] | Chain Network to use | No |
async initiateTopup(provider: PAYMENT_PROVIDER_TYPE, params: PaymentParams): Promise<void> {
if (!this.torusWalletInstance.isLoggedIn) throw TorusWalletPluginError.web3AuthNotConnected();
await this.torusWalletInstance.initiateTopup(provider, params);
}
export interface PaymentParams {
/**
* Address to send the funds to
*/
selectedAddress?: string;
/**
* Default fiat currency for the user to make the payment in
*/
selectedCurrency?: string;
/**
* Amount to buy in the selectedCurrency
*/
fiatValue?: number;
/**
* Cryptocurrency to buy
*/
selectedCryptoCurrency?: string;
/**
* Chain Network to use
*/
chainNetwork?: SUPPORTED_PAYMENT_NETWORK_TYPE;
}
export const PAYMENT_PROVIDER = {
MOONPAY: "moonpay",
WYRE: "wyre",
RAMPNETWORK: "rampnetwork",
XANPOOL: "xanpool",
MERCURYO: "mercuryo",
TRANSAK: "transak",
BANXA: "banxa",
} as const;
export const SUPPORTED_PAYMENT_NETWORK = {
MAINNET: "mainnet",
MATIC: "matic",
BSC_MAINNET: "bsc_mainnet",
AVALANCHE_MAINNET: "avalanche_mainnet",
XDAI: "xdai",
} as const;
Example
import { TorusWalletConnectorPlugin } from "@web3auth/torus-wallet-connector-plugin";
const torusPlugin = new TorusWalletConnectorPlugin({
torusWalletOpts: {},
walletInitOptions: {
whiteLabel: {
theme: { isDark: true, colors: { primary: "#00a8ff" } },
logoDark: "https://web3auth.io/images/w3a-L-Favicon-1.svg",
logoLight: "https://web3auth.io/images/w3a-D-Favicon-1.svg",
},
useWalletConnect: true,
enableLogging: true,
},
});
await web3auth.addPlugin(torusPlugin); // add plugin to web3auth instance
await torusPlugin.initiateTopup("moonpay", {
selectedAddress: "wallet_address",
selectedCurrency: "USD", // Fiat currency
fiatValue: 100, // Fiat Value
selectedCryptoCurrency: "ETH", // Cryptocurreny `SOL`, `MATIC` etc.
chainNetwork: "mainnet", // Blockchain network
});
Additional Reading
Initialiazing the Torus Plugin with a custom provider
You can also initialize the Torus Wallet UI Plugin with a custom provider. If your dApp is already initiating another provider, you can use that provider to initialize the Torus Wallet UI Plugin. This way it will be easier for you to use the Torus Wallet UI Plugin with your dApp.
Example
import { TorusWalletConnectorPlugin } from "@web3auth/torus-wallet-connector-plugin";
const torusPlugin = new TorusWalletConnectorPlugin({
torusWalletOpts: {
buttonPosition: "bottom-left",
},
walletInitOptions: {
whiteLabel: {
theme: { isDark: true, colors: { primary: "#00a8ff" } },
logoDark: "https://web3auth.io/images/w3a-L-Favicon-1.svg",
logoLight: "https://web3auth.io/images/w3a-D-Favicon-1.svg",
},
useWalletConnect: true,
enableLogging: true,
},
});
torusPlugin.initWithProvider(YOUR_CUSTOM_PROVIDER, userInfo);