Initialization

Create, initialize, and clean up a Torus web3 instance.

`Torus`

This is the main class of anything related to Torus

const Torus = require("@toruslabs/torus-embed");

Using ES6,

import Torus from "@toruslabs/torus-embed";

Then, create a new instance of Torus.

const torus = new Torus(options);

The Torus constructor takes an object with TorusCtorArgs as input.

Parameters

options - TorusCtorArgs (optional) : The options of the constructor
- buttonPosition - enum (optional) : The position of the Torus button. Supported values are top-left bottom-left top-right bottom-right

Returns

Object: The torus instance with all its methods and events.

Reference

interface TorusCtorArgs {
  buttonPosition?: "top-left" | "top-right" | "bottom-right" | "bottom-left";
}

Examples

const torus = new Torus();

const torus = new Torus({
  buttonPosition: "top-left", // default: 'bottom-left'
});

`init`

Initialize the torus object after creation

await torus.init(params);

Parameters

params - TorusParams (optional) : The parameters passed to initialize Torus object
- network - NetworkInterface (optional) : The network options. Used for setting a default network
- buildEnv - enum (optional): The build environment to use. Supported values are production development staging testing
- enableLogging - boolean (optional) : Enables/disables logging. Useful for debugging
- showTorusButton - boolean (optional) : Shows/Hides the Torus Button
- enabledVerifiers - VerifierStatus (optional) : Hides certain types of logins (default is true)
- integrity - IntegrityParams (optional) : Enables optional integrity checking (default is false)
- loginConfig - Array of login config items. Used to modify the default logins/ add new logins. Read more on Login Config.
- whiteLabel - A configuration object to customize UI, branding, and translations for your brand. Read more on White label.
- useLocalStorage-boolean (optional) : Prefers to use localStorage instead of sessionStorage for torus iframe. Allows longer lived sessions. By default torus iframe uses sessionStorage. Set this param as true to use localStorage.

Returns

Promise<void> : Returns a promise which resolves to void

Reference

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)
   * @default 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
   * @default 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
   * @default false
   */
  skipTKey?: boolean;
  /**
   * Prefers to use localStorage instead of sessionStorage for torus iframe. Allows longer lived sessions
   *
   * Defaults to false
   * @default false
   */
  useLocalStorage?: boolean;
}

interface VerifierStatus {
  /**
   * Defaults to true
   * @default true
   */
  google?: boolean;
  /**
   * Defaults to true
   * @default true
   */
  facebook?: boolean;
  /**
   * Defaults to true
   * @default true
   */
  reddit?: boolean;
  /**
   * Defaults to true
   * @default true
   */
  twitch?: boolean;
  /**
   * Defaults to true
   * @default true
   */
  discord?: boolean;
}

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
   * @default false
   */
  topupHide?: boolean;
  /**
   * Shows/hides billboard in torus-website.
   * Defaults to false
   * @default false
   */
  featuredBillboardHide?: boolean;
  /**
   * Shows/hides disclaimers on login page. Only works if special logins are hidden
   * Defaults to false
   * @default 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
   * @default 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>;
}
interface NetworkInterface {
  host:
    | "mainnet"
    | "rinkeby"
    | "ropsten"
    | "kovan"
    | "goerli"
    | "localhost"
    | "matic"
    | string;
  chainId?: number;
  networkName?: string;
  /**
   * Url of the block explorer
   */
  blockExplorer?: string;
  /**
   * Default currency ticker of the network (e.g: BNB)
   */
  ticker?: string;
  /**
   * Name for currency ticker (e.g: `Binance Coin`)
   */
  tickerName?: string;
}

interface IntegrityParams {
  check: boolean;
  hash?: string;
  version?: string;
}

Examples

await torus.init();

await torus.init({
  network: {
    host: "rinkeby", // default : 'mainnet'
  },
});

await torus.init({
  network: {
    host: "https://ethboston1.skalenodes.com:10062", // mandatory
    chainId: 1, // optional
    networkName: "Skale Network", // optional
  },
});

await torus.init({
  buildEnv: "staging", // uses staging.tor.us
  enableLogging: false, // default : false
  network: {
    host: "kovan", // default : 'mainnet'
  },
  showTorusButton: false, // default: true
  enabledVerifiers: {
    facebook: false, // default: true
  },
});

await torus.init({
  network: {
    host: "matic", // mandatory
  },
  showTorusButton: true, // default: true
});

`loginConfig`

Array of login config items. Used to modify the default logins/ add new logins under torus.init.

await torus.init({
  loginConfig: {
    [verifier]: loginConfigItem,
  },
});

Parameters

loginConfig - LoginConfig (optional) : Array of login configuration per verifier
- verifier - Verifier provided by torus as a key or a default verifier used by torus. You can also use your own dapp scoped verifier by creating a new verifier from developer dashboard under custom auth section.
loginConfigItem - LoginConfigItem : parameters per verifier
- typeOfLogin - LOGIN_TYPE: The type of login
- description - string (optional) : Description for button. If provided, it renders as a full length button. else, icon button
- clientId - string (optional) : Custom client_id. If not provided, we use the default for torus app
- logoHover - string (optional) : Logo to be shown on mouse hover. If not provided, we use the default for torus app
- logoLight - string (optional): Logo to be shown on dark background (dark theme). If not provided, we use the default for torus app
- logoDark - string (optional): Logo to be shown on light background (light theme). If not provided, we use the default for torus app
- showOnModal - boolean (optional): Whether to show the login button on modal or not
- jwtParameters - JwtParameters (optional): Custom JWT parameters to configure the login. Useful for Auth0 configuration

Reference

type LOGIN_TYPE =
  | "google"
  | "facebook"
  | "reddit"
  | "discord"
  | "twitch"
  | "apple"
  | "github"
  | "linkedin"
  | "twitter"
  | "weibo"
  | "line"
  | "jwt"
  | "email-password"
  | "passwordless";

interface LoginConfig {}

interface LoginConfigItem {
  typeOfLogin: LOGIN_TYPE;
  description?: string;
  clientId?: string;
  logoHover?: string;
  logoLight?: string;
  logoDark?: string;
  showOnModal?: boolean;
  jwtParameters?: JwtParameters;
}

interface JwtParameters {
  domain: string;
  client_id?: string;
  redirect_uri?: string;
  leeway?: number;
  verifierIdField?: string;
}

Example

await torus.init({
  loginConfig: {
    google: {
      description: "Login with google",
      clientId: "CLIENT_ID",
      logoHover: "https://sample.com/google-logo-hover.svg",
      logoLight: "https://sample.com/google-logo-light.svg",
      logoDark: "https://sample.com/google-logo-dark.svg",
      showOnModal: true,
    },
  },
});

`whiteLabel`

A configuration object to customize UI, branding, and translations for your brand.

Example

await torus.init({
  whiteLabel: {
    theme: {
      isDark: false,
      colors: {
        torusBrand1: "#282c34",
      },
    },
    logoDark: "https://tkey.surge.sh/images/Device.svg", // Dark logo for light background
    logoLight: "https://tkey.surge.sh/images/Device.svg", // Light logo for dark background
    topupHide: false,
    featuredBillboardHide: true,
    disclaimerHide: true,
    defaultLanguage: "en",
  },
  // Other options ...
});

Parameters

interface WhiteLabelParams {
  /**
   * Whitelabel theme
   */
  theme: ThemeParams;
  /**
   * Logo URL to be used in light mode (dark logo)
   */
  logoDark: string;
  /**
   * Logo URL to be used in dark mode (light logo)
   */
  logoLight: string;
  /**
   * Default translation language to used.
   * @default "en"
   */
  defaultLanguage: string;
  /**
   * Hide topup feature
   * @default false
   */
  topupHide: boolean;
  /**
   * Hide featured billboard
   * @default false
   */
  featuredBillboardHide: boolean;
  /**
   * Hide disclaimer section
   * @default false
   */
  disclaimerHide: boolean;
}

interface ThemeParams {
  /**
   * If true, enables dark mode
   * Defaults to false
   * @default false
   */
  isDark: boolean;
  /**
   * Colors object to customize colors in torus theme
   */
  colors: {
    torusBrand1: string; // Hex color for primary icons, texts, and buttons
  };
}

`cleanUp`

This cleans up the iframe and buttons created by torus package. If the user is logged in, it logs him out first and then cleans up.

await torus.cleanUp();

Returns

Promise<void> : Returns a promise which resolves to void.

Examples

await torus.cleanUp();

Torus​

init​

loginConfig​

whiteLabel​

cleanUp​

`Torus`

`init`

`loginConfig`

`whiteLabel`

`cleanUp`