Multi-Provider Connection

If you want to support the Universal Profile Browser Extension alongside other wallets, you can use third-party libraries like Web3Modal from Wallet Connect or Web3-Onboard from Blocknative. Both libraries are open-source, framework-agnostic JavaScript tools to improve the user's onboarding experience.

Wallet Connect

Image	Description
	Customizable Connection Window Remains connection on Page Refresh Lists supported EIP-1193 Extensions Automatically detects EIP-6963 Extensions Requires Wallet Connect Account ID

Web3 Onboard

Image	Description
	Customizable Connection Window Permanently Visible Connector Element Uses Custom Configuration Packages Disconnects on Page Refresh Lists EIP-1193 Extensions

Example Implementation

You can check out the implementation of both libraries within our dApp Boilerplate. You can change between multiple provider methods on the fly using the provider switcher component.

Installation

Wallet Connect

You can install the Web3 Modal using different configurations. The default package utilizes the Ethers.js library, which will be used in this example:

npm i @web3modal/ethers ethers

Web3 Onboard

You can install Web3-Onboard on the dApp using their core library, including all UI elements and hooks. In order to support the Universal Profile Browser Extension, you will have to install the @lukso/web3-onboard configuration that can be integrated as injected wallet.

npm i @web3-onboard/core @lukso/web3-onboard-config @web3-onboard/injected-wallets

Setup

After the installation, you can proceed to configure the library to support the LUKSO network and your dApp.

Wallet Connect

// Import the necessary components
import { createWeb3Modal, defaultConfig } from '@web3modal/ethers/react';

// Import the project ID from https://cloud.walletconnect.com
const projectId = 'YOUR_PROJECT_ID';

// Setup the Metadata
const walletConnectMetadata = {
  name: 'Example dApp',
  description: 'dApp using Wallet Connect',
  url: 'https://my.dapp.domain',
  icons: ['https://my.dapp.domain/icon.svg'],
};

// Initialize the Configuration Element
const walletConnectConfig = defaultConfig({
  metadata: walletConnectMetadata,
});

// Define the supported networks
const supportedChains = [
  // https://docs.lukso.tech/networks/mainnet/parameters
  {
    chainId: 42,
    name: 'LUKSO Mainnet',
    currency: 'LYX',
    explorerUrl: 'https://explorer.execution.mainnet.lukso.network/',
    rpcUrl: 'https://42.rpc.thirdweb.com/',
  },
  // https://docs.lukso.tech/networks/testnet/parameters
  {
    chainId: 4021,
    name: 'LUKSO Testnet',
    currency: 'LYXt',
    explorerUrl: 'https://explorer.execution.testnet.lukso.network/',
    rpcUrl: 'https://4201.rpc.thirdweb.com/',
  },
];

// Define chain images for the network screen
const walletConnectChainImages = {
  42: 'https://my.dapp.domain/lyx_symbol.svg',
  4201: 'https://my.dapp.domain/lyx_symbol.svg',
};

// Create the Web3 Modal Instance
const walletConnectInstance = createWeb3Modal({
  ethersConfig: walletConnectConfig,
  chains: supportedChains,
  projectId,
  chainImages: walletConnectChainImages,
  // OPTIONAL: Only show wallets that are installed by the user
  featuredWalletIds: ['NONE'],
});

Web3 Onboard

Referral Links

Be aware that anyone implementing Web3-Onboard can modify the download link to the extension.

success

The Web3-Onboard configuration and calls should be set up as a global context or component, accessible to every page or component of your application layout that is interacting with the blockchain.

// Import the necessary components
import Onboard, { OnboardAPI } from "@web3-onboard/core";
import { ConnectModalOptions } from "@web3-onboard/core/dist/types";
import injectedModule from "@web3-onboard/injected-wallets";
import luksoModule from "@lukso/web3-onboard-config";

// Initialize the LUKSO provider from this library
const luksoProvider = luksoModule();

// Define the download link for the extension
const UP_BROWSER_EXTENSION_URL =
  "https://chrome.google.com/webstore/detail/universal-profiles/abpickdkkbnbcoepogfhkhennhfhehfn?hl";

// Set up the injected wallet interface
const injectedWallets = injectedModule({
  /**
   * Add custom wallets here that you want
   * to inject into Web3-Onboard
   */
  custom: [luksoProvider],

  // OPTIONAL: Add sorting for supported wallets
  sort: (wallets) => {
    const sorted = wallets.reduce<any[]>((sorted, wallet) => {
      /**
       * Universal Profiles will be placed at the
       * top of the wallet connection screen
       *
       * Add other injected wallet names here
       * to adjust their order
       */
      if (wallet.label === "Universal Profiles") {
        sorted.unshift(wallet);
      } else {
        sorted.push(wallet);
      }
      return sorted;
    }, []);
    return sorted;
  },

  /**
   * OPTIONAL: Specify wallets that should still be displayed
   * in the list, even when unavailable in the browser
   */
  displayUnavailable: ["Universal Profiles"],
});

/**
 * Define at least one blockchain network that is able to
 * interact with the Universal Profile Browser Extension
 */
const supportedChains = [
  // https://docs.lukso.tech/networks/mainnet/parameters
  {
    id: 42,
    token: "LYX",
    label: "LUKSO Mainnet",
    rpcUrl: "https://42.rpc.thirdweb.com/",
  },
  // https://docs.lukso.tech/networks/testnet/parameters
  {
    id: 4021,
    token: "LYXt",
    label: "LUKSO Testnet",
    rpcUrl: "https://4201.rpc.thirdweb.com/",
  },
];

/**
 * OPTIONAL: Set up the app description of the
 * Web3-Onboard connection window
 */
const appInfo = {
  name: "My LUKSO App",
  /**
   * Pictures can either be a valid
   * Image URL or SVG as string
   *
   * The icon shows behind the extension picture
   * on the right side, while the connection
   * is being established
   */
  icon: "/my_app_icon.svg",
  /**
   * The logo shows left of the wallet list,
   * indicating the used app
   */
  logo: "<svg> ... </svg>",
  description: "My LUKSO App using Web3-Onboard",
  recommendedInjectedWallets: [
    /**
     * Add other injected wallets and their download links
     * to directly take users to the installation screen
     */
    {
      name: "Universal Profiles",
      url: UP_BROWSER_EXTENSION_URL,
    },
  ],
};

// OPTIONAL: Set up global installation notices
const connectionOptions: ConnectModalOptions = {
  iDontHaveAWalletLink: UP_BROWSER_EXTENSION_URL,
  removeWhereIsMyWalletWarning: true,
};

// Create the Web3-Onboard Component
const web3OnboardComponent: OnboardAPI = Onboard({
  wallets: [injectedWallets],
  chains: supportedChains,

  // OPTIONAL COMPONENTS:
  appMetadata: appInfo,
  connect: connectionOptions,
});

Connect

Wallet Connect

To set and access the Wallet Connect provider within your dApp, you can call the integrated open() method provided by the createWeb3Modal instance. The library will show a connection window with all supported wallets. You can then fetch the active account and set it as the default provider within your dApp.

ethers.js

// Trigger the connection process and screen
await walletConnectInstance.open();
// Subscribe to provider events, to track the connection
walletConnectInstance.subscribeProvider(
  ({ provider, address, isConnected, error }) => {
    if (error) {
      console.log('Wallet Connect Error:', error);
      return;
    }
    // If access was granted
    if (isConnected && provider && address) {
      const provider = new ethers.BrowserProvider(provider);
      walletConnectInstance.close();
    }
  },
);

web3.js

// Trigger the connection process and screen
await walletConnectInstance.open();
// Subscribe to provider events, to track the connection
walletConnectInstance.subscribeProvider(
  ({ provider, address, isConnected, error }) => {
    if (error) {
      console.log('Wallet Connect Error:', error);
      return;
    }
    // If access was granted
    if (isConnected && provider && address) {
      const provider = new Web3(provider);
      walletConnectInstance.close();
    }
  },
);

Web3 Onboard

To set and access the Web3-Onboard provider within your dApp, you can call the integrated connectWallet() method provided by the @web3-onboard/core library. The library will show a connection window with all supported wallets. You can then fetch the active account and set it as the default provider within your dApp.

ethers.js

// Trigger the connection process and screen
const connectedWallets = await web3OnboardComponent.connectWallet();
if (connectedWallets.length > 0) {
  // If a wallet has been connected, set it as default provider
  const provider = new ethers.BrowserProvider(connectedWallets[0].provider);
}

web3.js

// Trigger the connection process and screen
const connectedWallets = await web3OnboardComponent.connectWallet();
if (connectedWallets.length > 0) {
  // If a wallet has been connected, set it as default provider
  const provider = new Web3(connectedWallets[0].provider);
}

Disconnect

Wallet Connect

To disconnect your wallet, you have to call the disconnect() method provided by the createWeb3Modal instance.

// Close all connections
walletConnectInstance.disconnect();

Web3 Onboard

To disconnect your wallet, you have to call the disconnectWallet() method provided by the @web3-onboard/core library. This method requires specifying the wallet you wish to disconnect. You can obtain the necessary information from the state of the Web3-Onboard component, maintaining the current wallet connections.

// Retrieve the current onboard state
const onboardState = web3OnboardComponent.state.get();

// Extract the current connected wallets
const [currentWallet] = onboardState.wallets;

if (currentWallet) {
  // If there is an active connection, trigger the disconnect process
  await web3OnboardComponent.disconnectWallet({ label: currentWallet.label });
}

Maintaining compatibility

The Universal Profile Browser Extension only handles one active account connection at a time. This behavior differs from regular wallets. Therefore, the Disconnect methods should be called on every provider's accountsChanged and chainChanged events.

Sample Implementations

• Check our sample implementations for NextJS on the dApp Boilerplate.
• Test Web3-Onboard in our sandbox environment using up-test-dapp.lukso.tech.
• Find further information in the Web3-Onboard Documentation.
• Find further hooks and implementations in the Web3Modal Documentation