Usage of Core Kit SFA Web SDK

Once you've installed and successfully initialized Web3Auth, you can use it to authenticate your users. Further, you can use the native provider given by Web3Auth to connect the users to the respective blockchain network.

Natively, the instance of Web3Auth (called web3auth in our examples) returns the following functions:

• connect() - Logs in the User using the verifier, verifierId & idToken, which are mandatory, while subVerifierInfoArray and serverTimeOffset are optional.
• provider() - Returns the native provider that can be used to make different blockchain transactions.
• sessionId() - Returns the sessionId of the user as a string.
• authenticateUser() - Returns a promise of the UserAuthInfo object containing the idToken of the user.
• addChain() - Add chain configuration to the web3auth instance.
• switchChain() - Switches the chainId to one of the added chainIds.
• getUserInfo() - Returns the user information.
• logout() - Log out the user from the web3auth instance.

Logging in your User

connect(loginParams: LoginParams)

To log a user in the Web3Auth SFA Web SDK, you need to call the connect() function.

Variable	Description
loginParams	Mandatory login Parameters

Returns

connect(loginParams: LoginParams): Promise<IProvider | null>

LoginParams

connect(loginParams: LoginParams)

On successful login, the connect() function returns a IProvider instance. This instance contains the corresponding provider for your selected blockchain. You can use this provider to connect your user to the blockchain and perform transactions.

On unsuccessful login, this function will return a null value.

LoginParams

Table

Parameter	Description
verifier	Details of the verifier (verifier type, ie. torus, metamask, openlogin etc.). It's a mandatory parameter as a string.
verifierId	Verifier ID's value, sub or email value present in the idToken. It's a mandatory parameter as a string.
idToken	A newly created JWT Token that has not already been sent to Web3Auth or a Duplicate Token error will be thrown. It's a mandatory parameter as a string.
subVerifierInfoArray?	Sub verifier info. It's an optional parameter as a TorusSubVerifierInfo[].
serverTimeOffset?	Server time offset. It's an optional parameter as a number.

Type Declarations

export type LoginParams = {
  verifier: string;
  verifierId: string;
  idToken: string;
  subVerifierInfoArray?: TorusSubVerifierInfo[];
  serverTimeOffset?: number;
};

TorusSubVerifierInfo

Table

Parameter	Description
verifier	Details of the verifier (verifier type, ie. torus, metamask, openlogin etc.). It's a string mandatory parameter.
idToken	A newly created JWT Token that has not already been sent to Web3Auth or a Duplicate Token error will be thrown. It's a string mandatory parameter.

Interface

export interface TorusSubVerifierInfo {
  verifier: string;
  idToken: string;
}

Usage

await web3auth.connect({
  verifier: "verifier-name", // e.g. `web3auth-sfa-verifier` replace with your verifier name, and it has to be on the same network passed in init().
  verifierId: "verifier-id-value", // e.g. `Yux1873xnibdui` or `name@email.com` replace with your verifier id(sub or email)'s value.
  idToken: "JWT Token", // replace with your newly created unused JWT Token.
});

Get a native provider

provider()

Returns the native provider that can be used to make different blockchain transactions.

Returns

get provider(): IProvider | null;

Get sessionId

sessionId()

Returns the sessionId of the user as a string.

Returns

get sessionId(): string;

Authenticate the user

authenticateUser()

Returns a promise of the UserAuthInfo object containing the idToken of the user.

Returns

authenticateUser(): Promise<UserAuthInfo>;

UserAuthInfo

export type UserAuthInfo = {
  idToken: string;
};

Add a new chain

addChain(chainConfig: CustomChainConfig)

Add chain configuration to the web3auth instance.

Variable	Description
chainConfig	Mandatory chain-specific configuration as a CustomChainConfig type.

CustomChainConfig

Table

Parameter	Description
chainNamespace	Namespace of the chain. It's a mandatory parameter as a ChainNamespaceType type.
chainId	The chain id of the chain. It's a mandatory parameter as a string.
rpcTarget	RPC target URL for the chain. It's a mandatory parameter as a string.
wsTarget	Web socket target URL for the chain. It's an optional parameter as a string.
displayName	Display Name for the chain. It's an optional parameter as a string.
blockExplorerUrl	URL of the block explorer. It's an optional parameter as a string.
ticker	Default currency ticker of the network (e.g: ETH). It's an optional parameter as a string.
tickerName	Name for currency ticker (e.g: Ethereum). It's an optional parameter as a string.
decimals	Number of decimals for the currency ticker (e.g: 18). It's an optional parameter as a number.
logo	Logo for the token. It's an optional parameter as a string.
isTestnet	Whether the network is testnet or not. It's an optional parameter as a boolean.

Type Declarations

export declare const ADAPTER_NAMESPACES: {
  readonly EIP155: "eip155";
  readonly SOLANA: "solana";
  readonly CASPER: "casper";
  readonly XRPL: "xrpl";
  readonly MULTICHAIN: "multichain";
};

declare type ChainNamespaceType = (typeof CHAIN_NAMESPACES)[keyof typeof CHAIN_NAMESPACES];
export type CustomChainConfig = {
  chainNamespace: ChainNamespaceType;
  /**
   * The chain id of the chain
   */
  chainId: string;
  /**
   * RPC target Url for the chain
   */
  rpcTarget: string;
  /**
   * web socket target Url for the chain
   */
  wsTarget?: string;
  /**
   * Display Name for the chain
   */
  displayName?: string;
  /**
   * Url of the block explorer
   */
  blockExplorerUrl?: string;
  /**
   * Default currency ticker of the network (e.g: ETH)
   */
  ticker?: string;
  /**
   * Name for currency ticker (e.g: `Ethereum`)
   */
  tickerName?: string;
  /**
   * Number of decimals for the currency ticker (e.g: 18)
   */
  decimals?: number;
  /**
   * Logo for the token
   */
  logo?: string;
  /**
   * Whether the network is testnet or not
   */
  isTestnet?: boolean;
};

Switch the chain

switchChain(params: {chainId: string;})

Switch to one of the added chains

Variable	Description
chainId	Id of the chain to switch to. It's a mandatory parameter as a string

Logging out the user

logout()

Logs out the user and clears the session.

Note

@web3auth/single-factor-auth SDK only works for users who have not enabled MFA.

MFA enabled users

For MFA enabled users, you'll see Error("User has already enabled mfa, please use the @webauth/webauth-web sdk for login with mfa");

Example

Custom JWT Example

Custom JWT Example

import Web3Auth from "@web3auth/single-factor-auth";
import { EthereumPrivateKeyProvider } from "@web3auth/ethereum-provider";
import { CHAIN_NAMESPACES } from "@web3auth/base";
import jwt from "jsonwebtoken";
import fs from "fs";

// Use "openssl genrsa -out privateKey.pem 2048" to generate a private key
// Also, use this private key to generate a public key using "openssl rsa -in privateKey.pem -pubout -out publicKey.pem"
// Convert PEM to JWKS and expose it on a public URL, and make a web3auth verifier using that.
// Check out https://web3auth.io/docs/auth-provider-setup/byo-jwt-provider for more details.
var privateKey = fs.readFileSync("privateKey.pem");

// Define the chain config according to the chain you want to connect to
const chainConfig = {
  chainNamespace: CHAIN_NAMESPACES.EIP155,
  chainId: "0x1",
  rpcTarget: "https://rpc.ankr.com/eth",
  displayName: "Ethereum Mainnet",
  blockExplorerUrl: "https://etherscan.io",
  ticker: "ETH",
  tickerName: "Ethereum",
};

// Instantiate Web3Auth SFA SDK
const web3authSfa = new Web3Auth({
  clientId: "WEB3AUTH_CLIENT_ID", // Get your Client ID from the Web3Auth Dashboard
  web3AuthNetwork: "sapphire_mainnet", // Replace with your network name
  usePnPKey: false, // Setting this to true returns the same key as PnP Web SDK, By default, this SDK returns CoreKitKey.
});

// Instantiate Ethereum Provider
const privateKeyProvider = new EthereumPrivateKeyProvider({ config: { chainConfig } });

// Initialize Web3Auth SFA SDK
web3authSfa.init(privateKeyProvider);

const user = {
  id: "faj2720i2fdG7NsqznOKrthDvq43", // must be unique to each user
  name: "Mohammad Shahbaz Alam",
  email: "shahbaz@web3auth.io",
  profileImage: "https://avatars.githubusercontent.com/u/46641595?v=4",
};

// Login the user
const web3authSfaprovider = await web3auth.connect({
  verifier: "web3auth-sfa-verifier", // e.g. `web3auth-sfa-verifier` replace with your verifier name, and it has to be on the same network passed in init().
  verifierId: user.id, // e.g. `Yux1873xnibdui` or `name@email.com` replace with your verifier id(sub or email)'s value.
  idToken: jwt.sign(
    {
      sub: user.id, // must be unique to each user
      name: user.name,
      email: user.email,
      picture: user.profileImage,
      aud: "urn:my-resource-server", // -> to be used in Custom Authentication as JWT Field
      iss: "https://my-authz-server", // -> to be used in Custom Authentication as JWT Field
      iat: Math.floor(Date.now() / 1000),
      exp: Math.floor(Date.now() / 1000) + 60 * 60,
    },
    privateKey, // <-- privateKey to sign the JWT Token
    { algorithm: "RS256", keyid: "1bb9605c36e69386830202b2d" },
  ), // or replace it with your newly created unused JWT Token.
});

// Get the private key, The private key returned here is the CoreKit Key, since the usePnPKey is set to false.
const ethPrivateKey = await web3authSfaprovider.request({ method: "eth_private_key" });

console.log("ETH Private Key", ethPrivateKey);

Firebase JWT Example

Firebase JWT Example

import Web3Auth from "@web3auth/single-factor-auth";
import { EthereumPrivateKeyProvider } from "@web3auth/ethereum-provider";
import { CHAIN_NAMESPACES } from "@web3auth/base";
import { GoogleAuthProvider, getAuth, signInWithPopup, UserCredential } from "firebase/auth";

// Define the chain config according to the chain you want to connect to
const chainConfig = {
  chainNamespace: CHAIN_NAMESPACES.EIP155,
  chainId: "0x1",
  rpcTarget: "https://rpc.ankr.com/eth",
  displayName: "Ethereum Mainnet",
  blockExplorerUrl: "https://etherscan.io",
  ticker: "ETH",
  tickerName: "Ethereum",
};

// Your web app's Firebase configuration
const firebaseConfig = {
  apiKey: "AIzaSyB0nd9YsPLu-tpdCrsXn8wgsWVAiYEpQ_E",
  authDomain: "web3auth-oauth-logins.firebaseapp.com",
  projectId: "web3auth-oauth-logins",
  storageBucket: "web3auth-oauth-logins.appspot.com",
  messagingSenderId: "461819774167",
  appId: "1:461819774167:web:e74addfb6cc88f3b5b9c92",
};

// Instantiate Web3Auth SFA SDK
const web3authSfa = new Web3Auth({
  clientId: "WEB3AUTH_CLIENT_ID", // Get your Client ID from the Web3Auth Dashboard
  web3AuthNetwork: "sapphire_mainnet", // Replace with your network name
  usePnPKey: false, // Setting this to true returns the same key as PnP Web SDK, By default, this SDK returns CoreKitKey.
});

// Instantiate Ethereum Provider
const privateKeyProvider = new EthereumPrivateKeyProvider({ config: { chainConfig } });

// Initialize Web3Auth SFA SDK
web3authSfa.init(privateKeyProvider);

// Initialize Firebase and get idToken from Firebase
const app = initializeApp(firebaseConfig);
const auth = getAuth(app);
const googleProvider = new GoogleAuthProvider();
const res = await signInWithPopup(auth, googleProvider);
const idToken = await res.user.getIdToken(true);
// get sub value from firebase id token
const { sub } = parseToken(token); // parseToken is a function that parses the token and returns the payload.

// Login the user
const web3authSfaprovider = await web3auth.connect({
  verifier: "web3auth-sfa-verifier", // e.g. `web3auth-sfa-verifier` replace with your verifier name, and it has to be on the same network passed in init().
  verifierId: sub, // e.g. `Yux1873xnibdui` or `name@email.com` replace with your verifier id(sub or email)'s value.
  idToken: idToken, // or replace it with your newly created unused JWT Token.
});

// Get the private key, The private key returned here is the CoreKit Key, since the usePnPKey is set to false.
const ethPrivateKey = await web3authSfaprovider.request({ method: "eth_private_key" });

console.log("ETH Private Key", ethPrivateKey);