README.md

Wallet Connector

A framework-agnostic Ethereum provider solution to enable wallet connection for dApps.

Introduction

@whitelabel-solutions/wallet-connector is an easy-to-use library to support integration of the most common providers for wallet connection to your dApp. Following features are currently available:

• Connect and Disconnect to a multitude of providers
• Handle error, loading and connect states
• Specify a limited number of allowed chains
• Specify a desired chain and trigger a switch/add chain request
• Switch Chain
• Add Chain
• Store the current provider in local storage to facilitate sign-in for returning users
• Usage of peer dependencies gives the opportunity to use the latest version of a provider package

The library is framework-agnostic, meaning it is developed entirely in Typescript without any reliance on frameworks like React or Vue. However, it may of course be used in React or Vue.

Available connectors

More to come soon!

Connector	Docs
MetaMask	www.docs.metamask.io/guide/
Coinbase Wallet	www.docs.cloud.coinbase.com/wallet-sdk/docs
Wallet Connect	www.docs.walletconnect.com

Usage

1. Install @whitelabel-solutions/wallet-connector npm package

npm install --save @whitelabel-solutions/wallet-connector

# OR

yarn add @whitelabel-solutions/wallet-connector

2. Install only the necessary provider dependencies

# E.g. for MetaMask:
npm install --save @metamask/detect-provider

# OR

yarn add @metamask/detect-provider

# For all your providers. 
# Documentation on which dependencies to install for which provider will soon be added. In the meantime, please refer to the specific provider documentation.

3. Setup Connectors

import {
    MetaMask,
    WalletConnect,
    WalletLink,
} from "@whitelabel-solutions/wallet-connector"
import detectProvider from "@metamask/detect-provider"
import WalletConnectProvider from '@walletconnect/web3-provider';
import {CoinbaseWalletSDK} from "@coinbase/wallet-sdk";

const appName = "appName"
const infuraId = "infuraId"
const chainId = 1

const connectors = [
    MetaMask({detectProvider}),
    WalletConnect({WalletConnectProvider, options: {infuraId}}),
    CoinbaseWallet({
        CoinbaseWalletSDK,
        options: {
            appName,
            rpcUrl: "https://mainnet.infura.io/v3/" + infuraId,
            chainId
        },
    })
]

3. Initialize Connection

import { Connection } from "@whitelabel-solutions/wallet-connector"

const options = {
    allowedChainIds: [1, 3],
    desiredChainOrChainId: 1,
}

const connection = new Connection(options, connectors) // connectors from step 2

connection.loadFromCache() // use this to load the provider from local storage

4. Then you can add @whitelabel-solutions/wallet-connector as follows (e.g. in Vue)

<template>
    <ul>
        <li v-for="connector of connection.connectors" :key="connector.id">
            <button @click.prevent="connector.connect">
                {{ connector.name }}
            </button>
        </li>
    </ul>
</template>

You can find working examples in the example folder.

Options

The individual connectors are configured according to their respective package documentation. To configure the connection instance, the following options are available:

type ConnectionOptions = {
    allowedChainIds?: number[] | null // default: null
    desiredChainOrChainId?: number | AddEthereumChainParameter | null // default: null
    cache?: {
        enabled?: boolean // default: true
        key?: string // default: 'cached-connector'
    }
}

• If allowedChainIds option is set, the connector will validate if the user is connected to a matching chain.
• If desiredChainOrChainId option is set, the connector will validate if the user is connected to the matching chain and instantiate a chain switch if not. If a chain switch fails because it's unknown to the provider and the option is passed as an object, the connector will try to add the chain to the wallet.

Connection properties

interface IConnection {
    options: ConnectionOptions
    connectors: Record<string, IConnectorWrapper>
    activeConnectors: Record<string, IConnectorWrapper>
    activeConnector: IConnectorWrapper | undefined
    loadFromCache: () => Promise<IConnectorWrapper>
}

Connector properties

interface IConnectorWrapper {
    id: string
    name: string
    logo: string
    provider: IExternalProvider | undefined
    accounts: string[] | undefined
    chainId: number | undefined
    selectedAccount: string | undefined
    error: Error | undefined
    loading: boolean
    connected: boolean
    connect: () => Promise<IConnectorWrapper>
    disconnect: () => void
}

License

Distributed under the MIT License. See LICENSE.txt for more information.