Torus Solana Wallet UI Plugin

@web3auth/solana-wallet-connector-plugin

Torus Solana Wallet UI Plugin helps you get the functionalities of the Torus Solana Wallet into your Web3Auth Instance. It helps you use your Web3Auth key in the Torus Solana 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 gives you a provider from the Torus Solana 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 Solana Wallet UI Plugin for your dApp.

Installation

@web3auth/solana-wallet-connector-plugin

npm

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

Yarn

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

pnpm

pnpm add @web3auth/solana-wallet-connector-plugin

Initialisation

Import the SolanaWalletConnectorPlugin class from @web3auth/solana-wallet-connector-plugin.

import { SolanaWalletConnectorPlugin } from "@web3auth/solana-wallet-connector-plugin";

Assign the SolanaWalletConnectorPlugin 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 SolanaWalletConnectorPlugin(torusWalletOpts: {},
  walletInitOptions: {
    enableLogging: true,
  },);

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>	Parameters to customise your Torus Wallet Embed UI within the application	Yes

Interface

constructor(options: {
    torusWalletOpts?: TorusCtorArgs;
    walletInitOptions: Partial<TorusParams>;
});

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
modalZIndex?	number	Z-index of the modal and iframe	99999	No

Interface

export interface TorusCtorArgs {
  /**
   * Z-index of the modal and iframe
   * @defaultValue 99999
   */
  modalZIndex?: number;
}

walletInitOptions

The walletInitOptions from Solana Wallet is a required parameter that allows you to customise your Solana Wallet Embed Modal UI within the application. It takes the objet TorusParams as input which contains multiple parameters mentioned in the Solana Wallet Documentation.

Out of those mentioned parameters in Interface tab, the following 4 parameters are important for whitelabeling the plugin:

walletInitOptions: Partial<TorusParams>

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 Solana 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 solana-embed.	false
apiKey	string	No	Get it from https://dashboard.web3auth.io	N/A

Interface

export interface TorusParams {
  /**
   * Determines where the torus widget is visible on the page.
   * @defaultValue bottom-left
   */
  buttonPosition?: BUTTON_POSITION_TYPE;
  /**
   * Api key
   * Get yours today at {@link https://developer.web3auth.io | Dashboard}
   */
  apiKey?: string;

  /**
   * Torus Network Object
   */
  network?: NetworkInterface | NetworkLabel;
  /**
   * Build Environment of Torus.
   *
   * production uses https://solana.tor.us,
   *
   * development uses http://localhost:8080 (expects torus-website to be run locally),
   *
   * testing uses https://solana-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;
  /**
   * Prefers to use localStorage instead of sessionStorage for torus iframe. Allows longer lived sessions
   *
   * Defaults to false
   * @defaultValue false
   */
  useLocalStorage?: boolean;
  /**
   * Allows passing external data for initialize
   *
   * Defaults to empty object
   */
  extraParams?: { [keyof: string]: string };
  /**
   * Params to enable whitelabelling of torus website and widget
   */
  whiteLabel?: WhiteLabelParams;
}

export const BUTTON_POSITION = {
  BOTTOM_LEFT: "bottom-left",
  TOP_LEFT: "top-left",
  BOTTOM_RIGHT: "bottom-right",
  TOP_RIGHT: "top-right",
} as const;

export type BUTTON_POSITION_TYPE = typeof BUTTON_POSITION[keyof typeof BUTTON_POSITION];

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
name	string	No	App name to display in the UI	N/A
url	string	No	App url	N/A
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
defaultLanguage?	string	No	Language of whitelabel	Order of preference: Whitelabel language > user language (in torus-website) > browser language
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
topupHide?	boolean	No	Shows/hides topup option in torus-website/widget.	false
customTranslations?	string	No	Custom translations.	en - English

Interface

export interface WhiteLabelParams {
  /**
   * App name to display in the UI
   */
  name?: string;
  /**
   * App url
   */
  url?: string;
  /**
   * 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;
  /**
   * 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 - Solana Wallet, please check the Torus Solana 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

import { SolanaWalletConnectorPlugin } from "@web3auth/solana-wallet-connector-plugin";

const torusPlugin = new SolanaWalletConnectorPlugin({
  torusWalletOpts: {},
  walletInitOptions: {
    whiteLabel: {
      name: "Whitelabel Demo",
      theme: { isDark: true, colors: { torusBrand1: "#00a8ff" } },
      logoDark: "https://web3auth.io/images/w3a-L-Favicon-1.svg",
      logoLight: "https://web3auth.io/images/w3a-D-Favicon-1.svg",
      topupHide: true,
      defaultLanguage: "en",
    },
  },
});
await web3auth.addPlugin(torusPlugin);

Using the Torus Solana 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 Solana Wallet UI within your dApp and make RPC calls through that. To use the provider, use the following command:

Example

const blockhash = (await conn.getRecentBlockhash("finalized")).blockhash;
const TransactionInstruction = SystemProgram.transfer({
  fromPubkey: new PublicKey(publicKeys[0]),
  toPubkey: new PublicKey(publicKeys[1]),
  lamports: 0.1 * LAMPORTS_PER_SOL,
});
const transaction = new Transaction({
  recentBlockhash: blockhash,
  feePayer: new PublicKey(publicKeys[0]),
}).add(TransactionInstruction);

// torusWalletInstance will be available on torusPlugin once user is logged in.
// this will show transaction confirmation popup.
const res = await torusPlugin.torusWalletInstance.sendTransaction(transaction);

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"]	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
cyptoAmount?	number	Amount Cryptocurrency to buy	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;
  /**
   * Amount Cryptocurrency to buy
   */
  cryptoAmount?: number;
}

export const PAYMENT_PROVIDER = {
  MOONPAY: "moonpay",
  WYRE: "wyre",
  RAMPNETWORK: "rampnetwork",
  XANPOOL: "xanpool",
  MERCURYO: "mercuryo",
  TRANSAK: "transak",
} as const;

Example

import { SolanaWalletConnectorPlugin } from "@web3auth/solana-wallet-connector-plugin";

const torusPlugin = new SolanaWalletConnectorPlugin({
  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",
    },
  },
});

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

Additional Reading

Initialiazing the Torus Solana Wallet UI Plugin with a custom provider

You can also initialize the Torus Solana Wallet UI Plugin with a custom provider. If your dApp is already initiating another provider, you can use that provider to initialize the Torus Solana Wallet UI Plugin. This way it will be easier for you to use the Torus Solana Wallet UI Plugin with your dApp.

Example

import { SolanaWalletConnectorPlugin } from "@web3auth/solana-wallet-connector-plugin";

const torusPlugin = new SolanaWalletConnectorPlugin({
  torusWalletOpts: {},
  walletInitOptions: {
    whiteLabel: {
      name: "Whitelabel Demo",
      theme: { isDark: true, colors: { torusBrand1: "#00a8ff" } },
      logoDark: "https://web3auth.io/images/w3a-L-Favicon-1.svg",
      logoLight: "https://web3auth.io/images/w3a-D-Favicon-1.svg",
      topupHide: true,
      defaultLanguage: "en",
    },
    useWalletConnect: true,
    enableLogging: true,
  },
});

torusPlugin.initWithProvider(YOUR_CUSTOM_PROVIDER, userInfo);

Know more about how to use the Torus Solana Wallet Instance and provider