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
- Yarn
- pnpm
npm install --save @web3auth/solana-wallet-connector-plugin
yarn add @web3auth/solana-wallet-connector-plugin
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
- Interface
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 |
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
- Interface
TorusCtorArgs
Parameter | Type | Description | Default Value | Mandatory |
---|---|---|---|---|
modalZIndex? | number | Z-index of the modal and iframe | 99999 | No |
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
- 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 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 |
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
- Interface
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 |
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;
}
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
- Interface
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 |
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);