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

npm install --save @web3auth/torus-wallet-connector-plugin

Yarn

yarn add @web3auth/torus-wallet-connector-plugin

pnpm

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

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

Interface

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

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

Interface

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

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

Interface

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

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 de - German ja - Japanese ko - Korean zh - Mandarin es - Spanish fr - French pt - Portuguese nl - Dutch	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

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;
}

info

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

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

Interface

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);

Know more about how to use the Torus EVM Wallet Provider