@txnlab/use-wallet 1.3.1 → 2.0.0-alpha.0

package/README.md

@@ -1,115 +1,208 @@
-# @TxnLab/use-wallet
+# @txnlab/use-wallet
 
-React hooks for using Algorand compatible wallets with web applications. Flexible and extensible, `use-wallet` supports a variety of wallets and connection protocols. It also provides a simple interface for connecting, disconnecting, switching between accounts and signing transactions.
+`@txnlab/use-wallet` is a React library that provides a simplified, consistent interface for integrating multiple Algorand wallets into your decentralized applications (dApps).
 
-## Supported Providers
+## Overview
 
-- [Pera](https://perawallet.app/)
-- [MyAlgo](https://wallet.myalgo.com/home)
-- [Defly](https://defly.app)
-- [AlgoSigner](https://www.purestake.com/technology/algosigner)
-- [Exodus](https://www.exodus.com)
-- [WalletConnect](https://walletconnect.com)
-- [Daffi](https://www.daffi.me/)
-- [KMD](https://developer.algorand.org/docs/rest-apis/kmd)
+With the `useWallet` hook and utility functions, you can:
 
-## Demo
+- Easily add or remove wallet support with a few lines of code
+- Configure each wallet provider as needed for your application
+- Allow users to easily switch between active accounts and wallet providers
+- Sign and send transactions
+- Restore sessions for returning users
 
-Preview a basic implementation in [Storybook](https://txnlab.github.io/use-wallet) or check out [this example](https://github.com/gabrielkuettel/use-wallet-example).
+This library supports most Algorand wallet providers, including Defly, Pera, Daffi, and Exodus (see [Supported Wallet Providers](#supported-wallet-providers) for the full list).
 
-## Quick Start
+<!-- It provides an abstraction layer that handles the initialization, connection, and transaction signing logic, eliminating the need to interact with each wallet's individual API. -->
 
-### Yarn
+As of version 2.x it includes [WalletConnect 2.0 support](#walletconnect-20-support).
 
-```bash
-yarn add @txnlab/use-wallet
-```
+## Table of Contents
+
+- [Live Examples](#live-examples)
+- [Installation](#installation)
+- [Initializing Providers](#initializing-providers)
+- [The `useWallet` Hook](#the-usewallet-hook)
+- [Type Definitions](#type-definitions)
+- [Connect Menu](#connect-menu)
+- [Displaying Account Details](#displaying-account-details)
+- [Signing and Sending Transactions](#signing-and-sending-transactions)
+- [Checking Connection Status](#checking-connection-status)
+- [Supported Wallet Providers](#supported-wallet-providers)
+- [Legacy Wallet Support](#legacy-wallet-support)
+- [Provider Configuration](#provider-configuration)
+  - [Default configuration](#default-configuration)
+  - [Node configuration](#node-configuration)
+  - [Customize provider support](#customize-provider-support)
+  - [Provider objects](#provider-objects)
+  - [Static imports](#static-imports)
+- [WalletConnect 2.0 Support](#walletconnect-20-support)
+- [Migration Guide](#migration-guide)
+- [Local Development](#local-development)
+- [Used By](#used-by)
+- [License](#license)
+
+## Live Examples
+
+**Storybook demo** - https://txnlab.github.io/use-wallet
+
+**Next.js example**
 
-Install peer dependencies (if needed)
+- Demo - https://next-use-wallet.vercel.app/
+- Code - https://github.com/TxnLab/next-use-wallet
+
+**NFDomains** - https://app.nf.domains/
+
+## Installation
+
+Since this library uses React Hooks, your app will need to be using React 16.8 or higher.
+
+First, install the library
 
 ```bash
-yarn add algosdk @blockshake/defly-connect @perawallet/connect @randlabs/myalgo-connect @walletconnect/client algorand-walletconnect-qrcode-modal @json-rpc-tools/utils @daffiwallet/connect
+npm install @txnlab/use-wallet
 ```
 
-### NPM
+If you haven't already, install the Algorand JS SDK
 
 ```bash
-npm install @txnlab/use-wallet
+npm install algosdk
 ```
 
-Install peer dependencies (if needed)
+Finally, install the peer dependencies for the wallets you wish to support. To use the default configuration:
 
 ```bash
-npm install algosdk @blockshake/defly-connect @perawallet/connect @randlabs/myalgo-connect @walletconnect/client algorand-walletconnect-qrcode-modal @json-rpc-tools/utils @daffiwallet/connect
+npm install @perawallet/connect @blockshake/defly-connect @daffiwallet/connect
 ```
 
-### Set up the Wallet Provider
+Replace `npm install` with `yarn add` or `pnpm add` in the commands above, depending on your preferred package manager.
 
-In `app.js`, initialize the Wallet Provider so that the `useWallet` hook can be used in the child components, and use the `reconnectProviders` function to restore sessions for users returning to the app.
+## Initializing Providers
+
+In the root of your app, initialize the `WalletProvider` with the `useInitializeProviders` hook.
+
+This example initializes `useWallet` with the default configuration options. See [Provider Configuration](#provider-configuration) for more options.
 
 ```jsx
 import React from 'react'
-import { reconnectProviders, initializeProviders, WalletProvider } from '@txnlab/use-wallet'
-
-const walletProviders = initializeProviders()
+import { WalletProvider, useInitializeProviders } from '@txnlab/use-wallet'
 
 export default function App() {
-  // Reconnect the session when the user returns to the dApp
-  React.useEffect(() => {
-    reconnectProviders(walletProviders)
-  }, [])
+  // default configuration
+  const providers = useInitializeProviders()
+
+  return (
+    <WalletProvider value={providers}>
+      <div className="App">{/* ... */}</div>
+    </WalletProvider>
+  )
+}
+```
 
-  return <WalletProvider value={walletProviders}>...</WalletProvider>
+## The `useWallet` Hook
+
+The `useWallet` hook is used to access wallet provider and account state, send unsigned transactions to be signed, and send signed transactions to the node from anywhere in your app. It returns an object with the following properties:
+
+- `providers` - Array of wallet providers that have been initialized (see `Provider` in [Type Definitions](#type-definitions))
+- `activeAccount` - The currently active account in the active provider (see `Account` in [Type Definitions](#type-definitions))
+- `connectedAccounts` - Array of accounts from all connected wallet providers
+- `connectedActiveAccounts` - Array of accounts from the active wallet provider
+- `activeAddress` - The address of `activeAccount`
+- `status`, `isReady`, `isActive` - The current connection status, see [Check connection status](#check-connection-status)
+- `signTransactions` - Function that sends unsigned transactions to active wallet provider for signature
+- `sendTransactions` - Function that sends signed transactions to the node
+- `groupTransactionsBySender` - Utility function that groups transactions by sender address
+- `getAddress` - Utility function that returns the address of the `activeAccount`
+- `getAccountInfo` - Utility function that fetches `activeAccount` account information from the node
+- `getAssets` - Utility function that fetches `activeAccount` asset info/balances from the node
+- `signer` - Function used by the [KMD](#kmd-algorand-key-management-daemon) provider to sign transactions
+
+## Type Definitions
+
+### `Provider`
+
+```ts
+type Provider = {
+  accounts: Account[]
+  isActive: boolean
+  isConnected: boolean
+  connect: () => Promise<void>
+  disconnect: () => Promise<void>
+  reconnect: () => Promise<void>
+  setActiveProvider: () => void
+  setActiveAccount: (account: string) => void
+  metadata: Metadata
 }
 ```
 
-The `reconnectProviders` function is used to restore session states of wallets that rely on the `WalletConnect` protocol.
+Each provider has two connection states: `isConnected` and `isActive`.
 
-By default, all of the supported providers except for `KMD` are returned by `useConnectWallet`. An array can be passed to `initializeProviders` to determine which providers your dApp supports, as shown below.
+`isConnected` means that the user has authorized the provider in the app. Multiple providers can be connected at the same time.
 
-```jsx
-import { initializeProviders, PROVIDER_ID } from '@txnlab/use-wallet'
+`isActive` means that the provider is currently active and will be used to sign and send transactions.
+
+### `Account`
 
-const walletProviders = initializeProviders([PROVIDER_ID.KMD_WALLET, PROVIDER_ID.WALLET_CONNECT])
+```ts
+interface Account {
+  providerId: PROVIDER_ID
+  name: string
+  address: string
+  authAddr?: string
+}
 ```
 
-For more configuration options, see [Provider Configuration](#provider-configuration).
+The `activeAccount` is the account that will be used to sign and send transactions.
+
+To get the currently active wallet provider, read the `providerId` property of `activeAccount`.
+
+## Connect Menu
 
-### Connect
+In your app's UI you will need a menu for the user to `connect` or `disconnect` wallet providers, `setActiveProvider`, and `setActiveAccount`.
 
-Map through the `providers` object to list the providers and enable users to connect.
+This is a bare-bones example for demonstration purposes. For a styled example, see https://app.nf.domains/
 
 ```jsx
 import React from 'react'
 import { useWallet } from '@txnlab/use-wallet'
 
-export default function Connect() {
+export default function ConnectMenu() {
   const { providers, activeAccount } = useWallet()
 
-  // Map through the providers.
-  // Render account information and "connect", "set active", and "disconnect" buttons.
-  // Finally, map through the `accounts` property to render a dropdown for each connected account.
+  // 1. Map over `providers` array
+  // 2. Show the provider name/icon and "Connect", "Set Active", and "Disconnect" buttons
+  // 3. If active, map `provider.accounts` to render a select menu of connected accounts
+
   return (
     <div>
       {providers?.map((provider) => (
-        <div key={'provider-' + provider.metadata.id}>
+        <div key={provider.metadata.id}>
           <h4>
-            <img width={30} height={30} alt="" src={provider.metadata.icon} />
+            <img
+              width={30}
+              height={30}
+              alt={`${provider.metadata.name} icon`}
+              src={provider.metadata.icon}
+            />
             {provider.metadata.name} {provider.isActive && '[active]'}
           </h4>
+
           <div>
-            <button onClick={provider.connect} disabled={provider.isConnected}>
+            <button type="button" onClick={provider.connect} disabled={provider.isConnected}>
               Connect
             </button>
-            <button onClick={provider.disconnect} disabled={!provider.isConnected}>
+            <button type="button" onClick={provider.disconnect} disabled={!provider.isConnected}>
               Disconnect
             </button>
             <button
+              type="button"
               onClick={provider.setActiveProvider}
               disabled={!provider.isConnected || provider.isActive}
             >
               Set Active
             </button>
+
             <div>
               {provider.isActive && provider.accounts.length && (
                 <select
@@ -132,27 +225,51 @@ export default function Connect() {
 }
 ```
 
-Each provider has two connection states: `isConnected` and `isActive`.
+## Displaying Account Details
 
-`isConnected` means that the user has authorized the provider to talk to the dApp. The connection flow does not need to be restarted when switching to this wallet from a different one.
+The `activeAccount` object can be used to display details for the currently active account.
 
-`isActive` indicates that the provider is currently active and will be used to sign and send transactions when using the `useWallet` hook.
+```jsx
+import React from 'react'
+import { useWallet } from '@txnlab/use-wallet'
 
-The `activeAccount` is the primary account that is currently active and will be used to sign and send transactions.
+export default function Account() {
+  const { activeAccount } = useWallet()
 
-### Sign and send transactions
+  if (!activeAccount) {
+    return <p>No account active.</p>
+  }
 
-Construct a transaction using `algosdk`, and sign and send the transaction using the `signTransactions` and `sendTransactions` functions provided by the `useWallet` hook.
+  return (
+    <div>
+      <h4>Active Account</h4>
+      <p>
+        Name: <span>{activeAccount.name}</span>
+      </p>
+      <p>
+        Address: <span>{activeAccount.address}</span>
+      </p>
+      <p>
+        Provider: <span>{activeAccount.providerId}</span>
+      </p>
+    </div>
+  )
+}
+```
+
+## Signing and Sending Transactions
+
+Here is an example of a signing and sending simple pay transaction using `signTransactions` and `sendTransactions`.
 
 ```jsx
 import React from 'react'
+import algosdk from 'algosdk'
 import {
   useWallet,
   DEFAULT_NODE_BASEURL,
   DEFAULT_NODE_TOKEN,
   DEFAULT_NODE_PORT
 } from '@txnlab/use-wallet'
-import algosdk from 'algosdk'
 
 const algodClient = new algosdk.Algodv2(DEFAULT_NODE_TOKEN, DEFAULT_NODE_BASEURL, DEFAULT_NODE_PORT)
 
@@ -160,28 +277,29 @@ export default function Transact() {
   const { activeAddress, signTransactions, sendTransactions } = useWallet()
 
   const sendTransaction = async (from?: string, to?: string, amount?: number) => {
-    if (!from || !to || !amount) {
-      throw new Error('Missing transaction params.')
+    try {
+      if (!from || !to || !amount) {
+        throw new Error('Missing transaction params.')
+      }
+
+      const suggestedParams = await algodClient.getTransactionParams().do()
+
+      const transaction = algosdk.makePaymentTxnWithSuggestedParamsFromObject({
+        from,
+        to,
+        amount,
+        suggestedParams
+      })
+
+      const encodedTransaction = algosdk.encodeUnsignedTransaction(transaction)
+      const signedTransactions = await signTransactions([encodedTransaction])
+      const waitRoundsToConfirm = 4
+      const { id } = await sendTransactions(signedTransactions, waitRoundsToConfirm)
+
+      console.log('Successfully sent transaction. Transaction ID: ', id)
+    } catch (error) {
+      console.error(error)
     }
-
-    const suggestedParams = await algodClient.getTransactionParams().do()
-
-    const transaction = algosdk.makePaymentTxnWithSuggestedParamsFromObject({
-      from,
-      to,
-      amount,
-      suggestedParams
-    })
-
-    const encodedTransaction = algosdk.encodeUnsignedTransaction(transaction)
-
-    const signedTransactions = await signTransactions([encodedTransaction])
-
-    const waitRoundsToConfirm = 4
-
-    const { id } = await sendTransactions(signedTransactions, waitRoundsToConfirm)
-
-    console.log('Successfully sent transaction. Transaction ID: ', id)
   }
 
   if (!activeAddress) {
@@ -190,10 +308,7 @@ export default function Transact() {
 
   return (
     <div>
-      <button
-        onClick={() => sendTransaction(activeAddress, activeAddress, 1000)}
-        className="button"
-      >
+      <button type="button" onClick={() => sendTransaction(activeAddress, activeAddress, 1000)}>
         Sign and send transactions
       </button>
     </div>
@@ -201,41 +316,42 @@ export default function Transact() {
 }
 ```
 
-### Display account details
-
-The `activeAccount` object can be used to display details for the currently active account. For convenience, the `activeAddress` property shows the currently active address.
+### signTransactions
 
 ```jsx
-import React from 'react'
-import { useWallet } from '@txnlab/use-wallet'
+const signTransactions: (
+  transactions: Uint8Array[] | Uint8Array[][],
+  indexesToSign?: number[],
+  returnGroup?: boolean // defaults to true
+) => Promise<Uint8Array[]>
+```
 
-export default function Account() {
-  const { activeAccount } = useWallet()
+The `signTransactions` function will accept an array of transactions or an array of transaction groups.
 
-  if (!activeAccount) {
-    return <p>No account active.</p>
-  }
+You can optionally specify which transactions should be signed by providing an array of indexes as the second argument, `indexesToSign`.
 
-  return (
-    <div>
-      <h4>Active Account</h4>
-      <p>
-        Name: <span>{activeAccount.name}</span>
-      </p>
-      <p>
-        Address: <span>{activeAccount.address}</span>
-      </p>
-      <p>
-        Provider: <span>{activeAccount.providerId}</span>
-      </p>
-    </div>
-  )
-}
+By setting `returnGroup` to `false`, the returned promise will resolve to an array of signed transactions only. Otherwise it will return flat array of all transactions by default.
+
+### sendTransactions
+
+```jsx
+const sendTransactions: (
+  signedTransactions: Uint8Array[],
+  waitRoundsToConfirm?: number
+) => Promise<PendingTransactionResponse & { id: string }>
 ```
 
-### Check connection status
+If `signTransactions` is successful, the returned array of transactions can be passed to `sendTransactions` to be sent to the network.
+
+It will wait for confirmation before resolving the promise. Use the optional argument `waitRoundsToConfirm` to indicate how many rounds to wait for confirmation.
+
+The promise will resolve to an object containing the transaction `id` and the [`PendingTransactionResponse`](https://developer.algorand.org/docs/rest-apis/algod/#pendingtransactionresponse) from the Algorand REST API.
 
-The `isActive` and `isReady` properties can be used to check the status of the wallets. The `isActive` property determines whether or not an account is currently active. The `isReady` property shows if `use-wallet` has mounted and successfully read the connection status from the providers. These properties are useful when setting up client side access restrictions, for example, by redirecting a user if no wallet is active, as shown below.
+## Checking Connection Status
+
+The `isActive` and `isReady` properties can be used to check the status of the wallet providers. The `isActive` property determines whether or not an account is currently active. The `isReady` property indicates whether `use-wallet` has mounted and successfully read the connection status from the providers.
+
+These properties are useful when setting up client side access restrictions, for example, by redirecting a user if no wallet provider `isActive`, as shown below.
 
 ```jsx
 const { isActive, isReady } = useWallet()
@@ -251,107 +367,292 @@ useEffect(() => {
 })
 ```
 
+## Supported Wallet Providers
+
+### Pera Wallet
+
+- Website - https://perawallet.app/
+- Download Pera Mobile - [iOS](https://apps.apple.com/us/app/algorand-wallet/id1459898525) / [Android](https://play.google.com/store/apps/details?id=com.algorand.android)
+- Pera Web Wallet - https://web.perawallet.app/
+- Pera Connect - https://github.com/perawallet/connect
+
+### Defly Wallet
+
+- Website - https://defly.app/
+- Download Defly Wallet - [iOS](https://apps.apple.com/us/app/defly/id1602672723) / [Android](https://play.google.com/store/apps/details?id=io.blockshake.defly.app)
+- Defly Connect - https://github.com/blockshake-io/defly-connect
+
+### Daffi Wallet
+
+- Website - https://www.daffi.me/
+- Download Daffi Wallet - [iOS](https://apps.apple.com/kn/app/daffiwallet/id1659597876) / [Android](https://play.google.com/store/apps/details?id=me.daffi.daffi_wallet)
+- Daffi Connect - https://github.com/RDinitiativ/daffiwallet_connect
+
+### WalletConnect
+
+- Website - https://walletconnect.com/
+- Documentation - https://docs.walletconnect.com/
+- WalletConnect Cloud - https://cloud.walletconnect.com/
+- Web3Modal - https://web3modal.com/
+
+### Exodus Wallet
+
+- Website - https://www.exodus.com/
+- Download - https://www.exodus.com/download/
+
+### KMD (Algorand Key Management Daemon)
+
+- Documentation - https://developer.algorand.org/docs/rest-apis/kmd
+
+## Legacy Wallet Support
+
+Support for these wallets will be removed in a future release.
+
+### AlgoSigner
+
+- GitHub - https://github.com/PureStake/algosigner
+- EOL Press Release - https://www.algorand.foundation/news/algosigner-support-ending
+
+### MyAlgo
+
+- Website - https://wallet.myalgo.com/home
+- FAQ - https://wallet.myalgo.com/home#faq
+
 ## Provider Configuration
 
-The `initializeProviders` functon accepts a configuration object that can be used to configure the nodes that the providers use to send transactions, as shown below.
+### Default Configuration
+
+Calling `useInitializeProviders` with no arguments initializes the default supported wallet providers with the default node configuration:
+
+| Key                   | Default Value                                                                  |
+| --------------------- | ------------------------------------------------------------------------------ |
+| providers             | `[PROVIDER_ID.PERA, PROVIDER_ID.DEFLY, PROVIDER_ID.DAFFI, PROVIDER_ID.EXODUS]` |
+| nodeConfig.network    | `'mainnet'`                                                                    |
+| nodeConfig.nodeServer | `'https://mainnet-api.algonode.cloud'`                                         |
+| nodeConfig.nodeToken  | `''`                                                                           |
+| nodeConfig.nodePort   | `443`                                                                          |
+| algosdkStatic         | `undefined`                                                                    |
 
 ```jsx
-const walletProviders = initializeProviders([], {
-  network: 'devmodenet',
-  nodeServer: 'http://algod',
-  nodeToken: 'xxxxxxxxx',
-  nodePort: '8080'
+import React from 'react'
+import { WalletProvider, useInitializeProviders } from '@txnlab/use-wallet'
+
+export default function App() {
+  const providers = useInitializeProviders()
+
+  return (
+    <WalletProvider value={providers}>
+      <div className="App">{/* ... */}</div>
+    </WalletProvider>
+  )
+}
+```
+
+### Node configuration
+
+To configure the Algorand node that providers will use to send transactions, you can set the `nodeConfig` property. The `network` property should be specified as `mainnet`, `testnet`, `betanet` or the name of your local development network.
+
+Refer to your wallet providers' documentation to see which networks they support.
+
+```jsx
+const providers = await initializeProviders({
+  nodeConfig: {
+    network: 'testnet',
+    nodeServer: 'https://testnet-api.algonode.cloud',
+    nodeToken: '',
+    nodePort: '443'
+  }
 })
 ```
 
-Passing an empty array as the first argument enables all of the default providers. The `network` property should be specified as `betanet`, `testnet`, `mainnet` or the name of your local development network.
+### Customize provider support
 
-For more custom configuration options, the providers can be configured individually by creating an object and passing it to the `WalletProvider` where the key contains the provider ID, and the value calls the `init` function of the provider client. See below for an example:
+You can choose which wallet providers to support by setting the `providers` property to an array of provider IDs or [provider objects](#provider-objects). The example below shows provider IDs being used.
 
 ```jsx
-...
+// Only initialize Pera and Defly providers
+const providers = useInitializeProviders({
+  providers: [PROVIDER_ID.PERA, PROVIDER_ID.DEFLY]
+})
+```
 
-import {
-  PROVIDER_ID,
-  pera,
-  myalgo,
-} from "@txnlab/use-wallet";
-
-const walletProviders = {
-  [PROVIDER_ID.PERA]: pera.init({
-    clientOptions: {
-      shouldShowSignTxnToast: true,
-    },
-  }),
-  [PROVIDER_ID.MYALGO]: myalgo.init({
-    network: "devmodenet",
-    algodOptions: ["xxxxxxxxx", "http://algod", "8080"],
-    clientOptions: { disableLedgerNano: true },
-  }),
-};
-
-...
-
-<WalletProvider value={walletProviders}>
-  ...
-</WalletProvider>
+### Provider objects
+
+Some wallet providers have accompanying client libraries that can be configured. You can pass an object to the providers array to set `clientOptions`, as shown below.
+
+```jsx
+const providers = useInitializeProviders({
+  providers: [
+    PROVIDER_ID.DEFLY, // use default options for Defly Connect
+    { id: PROVIDER_ID.PERA, clientOptions: { shouldShowSignTxnToast: false } },
+    { id: PROVIDER_ID.MYALGO, clientOptions: { disableLedgerNano: false } },
+    PROVIDER_ID.EXODUS // Exodus has no client library
+  ]
+})
 ```
 
-## Static Imports
+See each provider's documentation for the available client options.
+
+You will need to use provider objects for [static imports](#static-imports), and for [WalletConnect 2.0](#walletconnect-20) support.
+
+**TypeScript:** The provider objects are type-safe, so your IDE should be able to provide autocomplete suggestions for the client's available options based on the `id` that is set.
 
-By default, `use-wallet` dynamically imports all of the dependencies for the providiers, as well as `algosdk`, to reduce bundle size.
+### Static Imports
 
-Some React frameworks, like [Remix](https://remix.run/), do not support dynamic imports. To get around this, those dependencies can be imported in your application and passed to the `useWallet` provider. See below for an example.
+By default, `use-wallet` dynamically imports all of the dependencies for the providers, as well as `algosdk`, to reduce bundle size.
+
+Some React frameworks, like [Remix](https://remix.run/), do not support dynamic imports. To get around this, provider clients can be imported in your application and passed to the provider objects `clientStatic` property.
+
+Set the imported `algosdk` to the `algosdkStatic` root property.
 
 ```jsx
-...
-
-import algosdk from "algosdk";
-import MyAlgoConnect from "@randlabs/myalgo-connect";
-import { PeraWalletConnect } from "@perawallet/connect";
-import { DeflyWalletConnect } from "@blockshake/defly-connect";
-import WalletConnect from "@walletconnect/client";
-import QRCodeModal from "algorand-walletconnect-qrcode-modal";
-
-const walletProviders = {
-  [PROVIDER_ID.PERA]: pera.init({
-    algosdkStatic: algosdk,
-    clientStatic: PeraWalletConnect,
-  }),
-  [PROVIDER_ID.MYALGO]: myalgo.init({
-    algosdkStatic: algosdk,
-    clientStatic: MyAlgoConnect,
-  }),
-  [PROVIDER_ID.DEFLY]: defly.init({
-    algosdkStatic: algosdk,
-    clientStatic: DeflyWalletConnect,
-  }),
-  [PROVIDER_ID.EXODUS]: exodus.init({
-    algosdkStatic: algosdk,
-  }),
-  [PROVIDER_ID.ALGOSIGNER]: algosigner.init({
-    algosdkStatic: algosdk,
-  }),
-  [PROVIDER_ID.WALLETCONNECT]: walletconnect.init({
-    algosdkStatic: algosdk,
-    clientStatic: WalletConnect,
-    modalStatic: QRCodeModal,
-  }),
-};
+import React from 'react'
+import algosdk from 'algosdk'
+import { PROVIDER_ID, WalletProvider, useInitializeProviders } from '@txnlab/use-wallet'
+import { DeflyWalletConnect } from '@blockshake/defly-connect'
+import { PeraWalletConnect } from '@perawallet/connect'
+import SignClient from '@walletconnect/sign-client'
+import { WalletConnectModal } from '@walletconnect/modal'
 
 export default function App() {
-  ...
+  const providers = useInitializeProviders({
+    providers: [
+      { id: PROVIDER_ID.PERA, clientStatic: PeraWalletConnect },
+      { id: PROVIDER_ID.DEFLY, clientStatic: DeflyWalletConnect },
+      {
+        id: PROVIDER_ID.WALLETCONNECT,
+        clientStatic: SignClient,
+        modalStatic: WalletConnectModal,
+        clientOptions: {
+          projectId: '<YOUR_PROJECT_ID>',
+          metadata: {
+            name: 'Example Dapp',
+            description: 'Example Dapp',
+            url: '#',
+            icons: ['https://walletconnect.com/walletconnect-logo.png']
+          }
+        }
+      },
+      PROVIDER_ID.EXODUS
+    ],
+    algosdkStatic: algosdk
+  })
 
   return (
-    <WalletProvider value={walletProviders}>
-      ...
+    <WalletProvider value={providers}>
+      <div className="App">{/* ... */}</div>
     </WalletProvider>
-  );
+  )
 }
+```
+
+## WalletConnect 2.0 Support
+
+`use-wallet` v2 introduces support for WalletConnect 2.0. This is a major upgrade to the WalletConnect protocol, and introduces a number of breaking changes for app developers to contend with.
+
+However, Algorand apps with `use-wallet` will be able to support the new protocol with minimal effort:
+
+1. **Obtain a project ID** - You will need to obtain a project ID from [WalletConnect Cloud](https://cloud.walletconnect.com/). This is a simple process, and there is no waiting period. Every app will need its own unique project ID.
+
+2. **Install peer dependencies** - Install `@walletconnect/sign-client` and `@walletconnect/modal`.
+
+3. **Update provider configuration** - You will need to use a provider object to initialize WalletConnect, and pass your `clientOptions` as shown below
 
+```jsx
+const providers = useInitializeProviders({
+  providers: [
+    {
+      id: PROVIDER_ID.WALLETCONNECT,
+      clientOptions: {
+        projectId: '<YOUR_PROJECT_ID>',
+        metadata: {
+          name: 'Example Dapp',
+          description: 'Example Dapp',
+          url: '#',
+          icons: ['https://walletconnect.com/walletconnect-logo.png']
+        }
+      }
+    }
+    // other providers...
+  ]
+})
 ```
 
-Note that some of the providers do not require static imports to be provided. This is usually the case of providers that are browser extensions.
+Since it requires the unique `projectId`, the WalletConnect provider is not initialized by default. This is a change from v1. If you want to support WalletConnect, it must be added to the `providers` array.
+
+See [Migrating to WalletConnect 2.0](#migrating-to-walletconnect-20) below for more information.
+
+## Migration Guide
+
+Version 2.x is a major version bump, and includes some breaking changes from 1.x.
+
+### initializeProviders
+
+`initializeProviders` is now asynchronous, and must be called from inside a `useEffect` hook.
+
+To simplify this, the `useInitializeProviders` hook is now provided, which calls `initializeProviders` internally. It accepts a single object as an argument.
+
+The providers array should be set as the `providers` property.
+
+```diff
+- const providers = initializeProviders([PROVIDER_ID.PERA, PROVIDER_ID.DEFLY])
++ const providers = useInitializeProviders({
++   providers: [PROVIDER_ID.PERA, PROVIDER_ID.DEFLY]
++ })
+```
+
+Node configuration should be set as the `nodeConfig` property.
+
+```diff
+- const providers = initializeProviders([], {
+-   network: 'testnet',
+-   nodeServer: 'https://testnet-api.algonode.cloud',
+-   nodeToken: '',
+-   nodePort: '443'
+- })
++ const providers = useInitializeProviders({
++   nodeConfig: {
++     network: 'testnet',
++     nodeServer: 'https://testnet-api.algonode.cloud',
++     nodeToken: '',
++     nodePort: '443'
++   }
++ })
+```
+
+See [Provider Configuration](#provider-configuration) for more details.
+
+### shouldShowSignTxnToast
+
+Pera Connect and Defly Connect both have a `shouldShowSignTxnToast` option that is set to `true` by default. `use-wallet` v1 set this to `false` by default, and required setting the option back to `true` to achieve the libraries' default behavior.
+
+In v2 this option is set to `true` by default. If your app has this option explicitly set you can remove it from your configuration. If you wish to disable the toast(s), you must now explicitly set the option to `false`.
+
+```jsx
+const providers = useInitializeProviders({
+  providers: [
+    { id: PROVIDER_ID.DEFLY, clientOptions: { shouldShowSignTxnToast: false } },
+    { id: PROVIDER_ID.PERA, clientOptions: { shouldShowSignTxnToast: false } }
+    // other providers...
+  ]
+})
+```
+
+### WalletConnect provider
+
+The WalletConnect provider now supports WalletConnect 2.0. To continue supporting this provider, or to add support to your application, you must install the `@walletconnect/sign-client` and `@walletconnect/modal` packages.
+
+```bash
+npm install @walletconnect/sign-client @walletconnect/modal
+```
+
+The peer dependencies for WalletConnect 1.x should be uninstalled.
+
+```bash
+npm uninstall @walletconnect/client @json-rpc-tools/utils algorand-walletconnect-qrcode-modal
+```
+
+WalletConnect is no longer initialized by default. To add support for WalletConnect, you must add it to the `providers` array, and pass your `clientOptions` as described in [WalletConnect 2.0 Support](#walletconnect-20-support) above.
 
 ## Local Development
 
@@ -365,7 +666,6 @@ yarn install
 
 ```bash
 yarn dev
-
 ```
 
 To develop against a local version of `use-wallet` in your application, do the following:
@@ -397,17 +697,19 @@ In the root of your application, run:
 ```bash
 cd node_modules/react
 yarn link
+cd ../react-dom
+yarn link
 ```
 
-In the root of `use-wallet` directory, run:
+In the root of the `use-wallet` directory, run:
 
 ```bash
-yarn link react
+yarn link react react-dom
 ```
 
 ## Used By
 
-Are you using `@txnlab/use-wallet`? We'd love to include you here. Let us know! [Twitter](https://twitter.com/NFDomains) | [Discord](https://discord.gg/7XcuMTfeZP) | [Email](mailto:admin@txnlab.dev)
+Are you using `@txnlab/use-wallet`? We'd love to include your project here. Let us know! [Twitter](https://twitter.com/NFDomains) | [Discord](https://discord.gg/7XcuMTfeZP) | [Email](mailto:admin@txnlab.dev)
 
 - [@algoscan/use-wallet-ui](https://github.com/algoscan/use-wallet-ui)
 - [@algoworldnft/algoworld-swapper](https://github.com/algoworldnft/algoworld-swapper)