Web3Auth PnP Web SDK v7 to v10 Migration Guide

This guide will help you upgrade your Web3Auth PnP SDK integration from v7 directly to the unified Web3Auth PnP Web SDK v10, focusing on core package and initialization changes.

Why Migrate to v10?

Web3Auth v10 consolidates functionality into a single powerful SDK that centralizes configuration in the Dashboard and eliminates frontend adapter complexity.

Key improvements from v7 to v10:

• Unified SDK Package: Single @web3auth/modal package replaces multiple adapter packages
• Dashboard-Centric Configuration: Chain configurations managed via Web3Auth Developer Dashboard
• Simplified Integration: No more manual OpenLoginAdapter registration or privateKeyProvider setup
• Enhanced Developer Experience: Cleaner API with better TypeScript support

Installation

Update to the unified v10 SDK package:

npm

npm uninstall @web3auth/modal @web3auth/openlogin-adapter @web3auth/wallet-connect-v2-adapter @web3auth/metamask-adapter @web3auth/phantom-adapter @web3auth/wallet-services-plugin
npm install @web3auth/modal

Yarn

yarn remove @web3auth/modal @web3auth/openlogin-adapter @web3auth/wallet-connect-v2-adapter @web3auth/metamask-adapter @web3auth/phantom-adapter @web3auth/wallet-services-plugin
yarn add @web3auth/modal

pnpm

pnpm remove @web3auth/modal @web3auth/openlogin-adapter @web3auth/wallet-connect-v2-adapter @web3auth/metamask-adapter @web3auth/phantom-adapter @web3auth/wallet-services-plugin
pnpm add @web3auth/modal

Bun

bun remove @web3auth/modal @web3auth/openlogin-adapter @web3auth/wallet-connect-v2-adapter @web3auth/metamask-adapter @web3auth/phantom-adapter @web3auth/wallet-services-plugin
bun add @web3auth/modal

For custom blockchain configurations:

npm

npm install @web3auth/ethereum-provider

Yarn

yarn add @web3auth/ethereum-provider

pnpm

pnpm add @web3auth/ethereum-provider

Bun

bun add @web3auth/ethereum-provider

Breaking Changes from v7 to v10

1. Unified SDK Package Structure

v7 used separate packages:

import { Web3Auth } from "@web3auth/modal";
import { OpenloginAdapter } from "@web3auth/openlogin-adapter";
import { MetamaskAdapter } from "@web3auth/metamask-adapter";
import { WalletConnectV2Adapter } from "@web3auth/wallet-connect-v2-adapter";

v10 uses a single package:

import { Web3Auth } from "@web3auth/modal";
// Most functionality is now built-in - no separate adapters needed for basic use cases

2. OpenLoginAdapter → Built-in (v7→v10)

In v7, authentication required OpenloginAdapter. V10 eliminates the need for adapter registration:

import { OpenloginAdapter } from "@web3auth/openlogin-adapter";

const openloginAdapter = new OpenloginAdapter({
  loginSettings: {
    mfaLevel: "optional",
  },
  adapterSettings: {
    whiteLabel: {
      appName: "W3A Heroes",
      logoLight: "https://web3auth.io/images/web3auth-logo.svg",
      logoDark: "https://web3auth.io/images/web3auth-logo---Dark.svg",
    },
  },
});

web3auth.configureAdapter(openloginAdapter);
await web3auth.initModal();

// Authentication is built-in - no adapter configuration needed
await web3auth.init();

3. Chain Configuration Centralization

v7 required manual chain and provider configuration:

import { EthereumPrivateKeyProvider } from "@web3auth/ethereum-provider";

const chainConfig = {
  chainNamespace: "eip155",
  chainId: "0x1",
  rpcTarget: "https://rpc.ethereum.org",
  displayName: "Ethereum Mainnet",
  blockExplorerUrl: "https://etherscan.io/",
  ticker: "ETH",
  tickerName: "Ethereum",
  logo: "https://images.toruswallet.io/eth.svg",
};

const privateKeyProvider = new EthereumPrivateKeyProvider({
  config: { chainConfig },
});

const web3auth = new Web3Auth({
  clientId: "YOUR_CLIENT_ID",
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  privateKeyProvider,
  uiConfig: {
    appName: "W3A Heroes",
    logoLight: "https://web3auth.io/images/web3auth-logo.svg",
    logoDark: "https://web3auth.io/images/web3auth-logo---Dark.svg",
  },
});

const web3auth = new Web3Auth({
  clientId: "YOUR_CLIENT_ID",
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  // Chain configuration and branding managed via Web3Auth Developer Dashboard
});

Configure your chains and branding on the Web3Auth Developer Dashboard instead of in code.

4. Method Name Changes

Key method updates:

// v7 method names
await web3auth.authenticateUser(); // Get ID token
await web3auth.addChain(newChain); // Add new chain
await web3auth.switchChain({ chainId: "0x1" }); // Switch chains

// v10 method names
await web3auth.getIdentityToken(); // Get ID token
await web3auth.addChain(newChain); // Add new chain (unchanged)
await web3auth.switchChain({ chainId: "0x1" }); // Switch chains (unchanged)

Additional Migration Guides

For specific functionality migrations, refer to these supplementary guides:

External Wallet Adapters: If you used external wallet adapters in v7, see the 🔌 External Wallet Adapters Migration Guide for migrating to automatic detection.

Wallet Services: If you used the @web3auth/wallet-services-plugin in v7, see the 🛠️ Wallet Services Migration Guide for migrating to the built-in integration.

Whitelabeling and UI Customization: If you had whitelabeling configurations in v7, see the 📋 Whitelabeling Migration Guide for detailed steps.

Custom Authentication: If you used custom verifiers in v7, see the 🔐 Custom Authentication Migration Guide for migrating to the new Connections system.

Complete Migration Example

Here's a complete before/after example showing the migration from v7 to v10:

v7 Implementation

import { Web3Auth } from "@web3auth/modal";
import { OpenloginAdapter } from "@web3auth/openlogin-adapter";
import { EthereumPrivateKeyProvider } from "@web3auth/ethereum-provider";
import { MetamaskAdapter } from "@web3auth/metamask-adapter";
import {
  WalletConnectV2Adapter,
  getWalletConnectV2Settings,
} from "@web3auth/wallet-connect-v2-adapter";

// Chain configuration
const chainConfig = {
  chainNamespace: "eip155",
  chainId: "0x1",
  rpcTarget: "https://rpc.ethereum.org",
  displayName: "Ethereum Mainnet",
  blockExplorerUrl: "https://etherscan.io/",
  ticker: "ETH",
  tickerName: "Ethereum",
  logo: "https://images.toruswallet.io/eth.svg",
};

// Provider setup
const privateKeyProvider = new EthereumPrivateKeyProvider({
  config: { chainConfig },
});

// SDK initialization
const web3auth = new Web3Auth({
  clientId: "YOUR_CLIENT_ID",
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  privateKeyProvider,
  uiConfig: {
    appName: "W3A Heroes",
    logoLight: "https://web3auth.io/images/web3auth-logo.svg",
    logoDark: "https://web3auth.io/images/web3auth-logo---Dark.svg",
  },
});

// OpenLogin adapter
const openloginAdapter = new OpenloginAdapter({
  loginSettings: {
    mfaLevel: "optional",
  },
  adapterSettings: {
    whiteLabel: {
      appName: "W3A Heroes",
      logoLight: "https://web3auth.io/images/web3auth-logo.svg",
      logoDark: "https://web3auth.io/images/web3auth-logo---Dark.svg",
    },
  },
});
web3auth.configureAdapter(openloginAdapter);

// External adapters
const metamaskAdapter = new MetamaskAdapter();
web3auth.configureAdapter(metamaskAdapter);

const defaultWcSettings = await getWalletConnectV2Settings("eip155", ["1"], "projectId");
const walletConnectV2Adapter = new WalletConnectV2Adapter({
  adapterSettings: { qrcodeModal: WalletConnectModal, ...defaultWcSettings.adapterSettings },
  loginSettings: { ...defaultWcSettings.loginSettings },
});
web3auth.configureAdapter(walletConnectV2Adapter);

await web3auth.initModal();

// Usage
await web3auth.connect();
const idToken = await web3auth.authenticateUser();

v10 Implementation

import { Web3Auth } from "@web3auth/modal";

// SDK initialization - much simpler!
const web3auth = new Web3Auth({
  clientId: "YOUR_CLIENT_ID",
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  // Chain config and branding managed via dashboard
});

await web3auth.init();

// Usage
await web3auth.connect();
const idToken = await web3auth.getIdentityToken();

// External wallets automatically detected - no manual setup needed

Key Differences Summary

Feature	v7	v10
Package	@web3auth/modal + adapters	@web3auth/modal only
Authentication	OpenloginAdapter required	Built-in
Chain Config	Manual chainConfig + privateKeyProvider	Dashboard configuration
External Wallets	Manual adapter setup	Automatic detection
Branding	uiConfig + OpenloginAdapter whiteLabel	Dashboard configuration
ID Token	authenticateUser()	getIdentityToken()

Benefits of v10 Migration

1. Unified Architecture: Single package handles all use cases
2. Reduced Complexity: No manual adapter configuration or chain setup
3. Dashboard Control: Centralized configuration management
4. Better Developer Experience: Cleaner API with improved TypeScript support
5. Future-Proof: Aligned with Web3Auth's long-term architectural direction

Next Steps

1. Update your package dependencies
2. Remove adapter configurations and use the unified SDK
3. Configure your chains and branding on the Web3Auth Developer Dashboard
4. Update method names (authenticateUser → getIdentityToken)
5. Test your application with the new unified architecture

For any specific migration challenges, refer to the supplementary guides linked above or consult the Web3Auth documentation.