or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdethereum-provider.mdindex.mdnetwork-management.mdwallet-operations.mdwidget-management.md
tile.json

tessl/npm-toruslabs--torus-embed

Embeddable Web3 authentication solution that integrates OAuth logins with Multi Party Computation technology for passwordless wallet access

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@toruslabs/torus-embed@5.0.x

To install, run

npx @tessl/cli install tessl/npm-toruslabs--torus-embed@5.0.0

index.mddocs/

Torus Embed

Torus Embed is a JavaScript/TypeScript library that provides seamless Web3 authentication and wallet integration for decentralized applications. It creates an embeddable iframe-based wallet solution that aggregates OAuth logins (Google, Twitter, Discord, etc.) with Multi Party Computation (MPC) technology to provide passwordless authentication for Web3 applications.

Package Information

  • Package Name: @toruslabs/torus-embed
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @toruslabs/torus-embed

Core Imports

import Torus from "@toruslabs/torus-embed";
import { 
  TorusInpageProvider,
  NetworkInterface,
  TorusParams,
  TorusCtorArgs,
  UserInfo,
  LOGIN_TYPE,
  BUTTON_POSITION_TYPE,
  PaymentParams,
  PAYMENT_PROVIDER_TYPE
} from "@toruslabs/torus-embed";

For CommonJS:

const Torus = require("@toruslabs/torus-embed").default;
const { 
  TorusInpageProvider,
  NetworkInterface,
  TorusParams,
  UserInfo
} = require("@toruslabs/torus-embed");

Basic Usage

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

// Initialize Torus
const torus = new Torus({
  buttonPosition: "bottom-left",
  modalZIndex: 99999
});

// Initialize the widget
await torus.init({
  buildEnv: "production",
  network: {
    host: "mainnet"
  },
  showTorusButton: true
});

// Login user
const accounts = await torus.login({ verifier: "google" });
console.log("User accounts:", accounts);

// Access the Ethereum provider
const provider = torus.provider;
const balance = await provider.request({
  method: "eth_getBalance",
  params: [accounts[0], "latest"]
});

Architecture

Torus Embed is built around several key components:

  • Torus Class: Main API for widget initialization, authentication, and wallet operations
  • TorusInpageProvider: EIP-1193 compliant Ethereum provider for Web3 interactions
  • Iframe Communication: Secure communication between host application and Torus wallet iframe
  • OAuth Integration: Multi-provider OAuth authentication with verifier management
  • Network Management: Support for multiple Ethereum networks and custom RPC endpoints
  • Payment Integration: Built-in support for multiple fiat-to-crypto providers

Capabilities

Widget Initialization and Management

Core functionality for initializing and managing the Torus wallet widget, including configuration, display control, and lifecycle management.

class Torus {
  constructor(args?: TorusCtorArgs);
  init(params?: TorusParams): Promise<void>;
  clearInit(): void;
  cleanUp(): Promise<void>;
  hideTorusButton(): void;
  showTorusButton(): void;
}

interface TorusCtorArgs {
  buttonPosition?: BUTTON_POSITION_TYPE;
  buttonSize?: number;
  modalZIndex?: number;
  apiKey?: string;
}

interface TorusParams {
  network?: NetworkInterface;
  buildEnv?: TORUS_BUILD_ENV_TYPE;
  enableLogging?: boolean;
  showTorusButton?: boolean;
  loginConfig?: LoginConfig;
  integrity?: IntegrityParams;
  whiteLabel?: WhiteLabelParams;
  useWalletConnect?: boolean;
  mfaLevel?: "none" | "default" | "optional" | "mandatory";
}

Widget Management

User Authentication

OAuth-based authentication system supporting multiple providers (Google, Facebook, Discord, etc.) with session management and user profile access.

login(params?: TorusLoginParams): Promise<string[]>;
logout(): Promise<void>;
getUserInfo(message: string): Promise<UserInfo>;
loginWithPrivateKey(loginParams: {
  privateKey: string;
  userInfo: Omit<UserInfo, "isNewUser">;
}): Promise<boolean>;

interface TorusLoginParams {
  verifier?: string;
  login_hint?: string;
}

interface UserInfo {
  email: string;
  name: string;
  profileImage: string;
  verifier: string;
  verifierId: string;
  isNewUser: boolean;
  typeOfLogin: LOGIN_TYPE;
}

Authentication

Network and Provider Management

Ethereum network configuration and Web3 provider management with support for multiple networks and custom RPC endpoints.

setProvider(network: NetworkInterface): Promise<void>;
getPublicAddress(args: VerifierArgs): Promise<string | TorusPublicKey>;

interface NetworkInterface {
  host: ETHEREUM_NETWORK_TYPE | string;
  chainId?: number;
  networkName?: string;
  blockExplorer?: string;
  ticker?: string;
  tickerName?: string;
}

interface VerifierArgs {
  verifier: "google" | "reddit" | "discord";
  verifierId: string;
  isExtended?: boolean;
}

Network Management

Ethereum Provider Interface

EIP-1193 compliant Ethereum provider for Web3 interactions, RPC requests, and blockchain operations.

class TorusInpageProvider {
  readonly chainId: string | null;
  readonly selectedAddress: string | null;
  readonly networkVersion: string | null;
  readonly isTorus: true;
  
  isConnected(): boolean;
  request<T>(args: RequestArguments): Promise<Maybe<T>>;
  sendAsync(payload: JRPCRequest<unknown>, callback: Function): void;
}

interface RequestArguments {
  method: string;
  params?: unknown[] | Record<string, unknown>;
}

Ethereum Provider

Wallet Operations and Payments

Wallet interface management and payment integration with support for multiple fiat-to-crypto providers and WalletConnect.

showWallet(path: WALLET_PATH, params?: Record<string, string>): void;
initiateTopup(provider: PAYMENT_PROVIDER_TYPE, params: PaymentParams): Promise<boolean>;
showWalletConnectScanner(): Promise<boolean>;

interface PaymentParams {
  selectedAddress?: string;
  selectedCurrency?: string;
  fiatValue?: number;
  selectedCryptoCurrency?: string;
  chainNetwork?: SUPPORTED_PAYMENT_NETWORK_TYPE;
}

type WALLET_PATH = "transfer" | "topup" | "home" | "settings" | "history" | "discover";

Wallet Operations

Core Types

type BUTTON_POSITION_TYPE = "bottom-left" | "top-left" | "bottom-right" | "top-right";

type LOGIN_TYPE = 
  | "google" | "facebook" | "reddit" | "discord" | "twitch" | "apple"
  | "github" | "linkedin" | "twitter" | "weibo" | "line" | "jwt"
  | "email_password" | "passwordless" | "wechat" | "kakao";

type ETHEREUM_NETWORK_TYPE = 
  | "sepolia" | "mainnet" | "goerli" | "localhost" | "matic" | "mumbai"
  | "xdai" | "bsc_mainnet" | "bsc_testnet";

type PAYMENT_PROVIDER_TYPE = 
  | "moonpay" | "rampnetwork" | "mercuryo" | "transak" | "banxa";

type SUPPORTED_PAYMENT_NETWORK_TYPE =
  | "mainnet" | "matic" | "bsc_mainnet" | "avalanche_mainnet"
  | "xdai" | "arbitrum_mainnet" | "optimism_mainnet";

type TORUS_BUILD_ENV_TYPE =
  | "production" | "development" | "binance" | "testing"
  | "lrc" | "beta" | "bnb" | "polygon" | "alpha";

interface TorusPublicKey {
  address: string;
  X: string;
  Y: string;
}

type Maybe<T> = Partial<T> | null | undefined;

interface WhiteLabelParams {
  theme: ThemeParams;
  defaultLanguage?: string;
  logoDark: string;
  logoLight: string;
  topupHide?: boolean;
  featuredBillboardHide?: boolean;
  disclaimerHide?: boolean;
  tncLink?: LocaleLinks<string>;
  privacyPolicy?: LocaleLinks<string>;
  contactLink?: LocaleLinks<string>;
  customTranslations?: LocaleLinks<unknown>;
}

interface ThemeParams {
  isDark: boolean;
  colors: Record<string, string>;
}

interface IntegrityParams {
  version?: string;
}

interface LoginConfig {
  [verifier: string]: LoginConfigItem;
}

interface LoginConfigItem {
  name: string;
  typeOfLogin: LOGIN_TYPE;
  description?: string;
  clientId?: string;
  logoHover?: string;
  logoLight?: string;
  logoDark?: string;
  showOnModal?: boolean;
  showOnMobile?: boolean;
  jwtParameters?: JwtParameters;
  mainOption?: boolean;
  showOnDesktop?: boolean;
  priority?: number;
}

interface JwtParameters {
  domain: string;
  client_id?: string;
  redirect_uri?: string;
  leeway?: number;
  verifierIdField?: string;
  isVerifierIdCaseSensitive?: boolean;
  [key: string]: unknown;
}

interface LocaleLinks<T> {
  en?: T;
  ja?: T;
  ko?: T;
  de?: T;
  zh?: T;
  es?: T;
}