Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/aragon/use-wallet

👛 useWallet() · All-in-one solution to connect a dapp to an Ethereum provider.
https://github.com/aragon/use-wallet

dapp ethereum ethereum-provider hooks javascript react react-hooks web3

Last synced: about 1 month ago
JSON representation

👛 useWallet() · All-in-one solution to connect a dapp to an Ethereum provider.

Awesome Lists containing this project

README 

        
# 👛 useWallet()



[](https://www.npmjs.com/package/use-wallet) [](https://bundlephobia.com/result?p=use-wallet)



useWallet() allows dapp users to connect to the provider of their choice in a way that is as straightforward as possible. It provides a common data structure for any connected account, no matter what provider has been chosen by the user. It aims to provide some features that are often reimplemented by dapp developers: connecting to a wallet, keeping track of transactions, and more (submit a [issue](https://github.com/aragon/use-wallet/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) or PR!).



## Features



- All-in-one solution to connect to Ethereum providers.

- Completely library agnostic (use Web3.js, ethers.js, …).

- Provides the current balance.

- Keeps track of the recent transactions (coming soon).



### Opinionated?



Oh yes:



- React only.

- Ethereum only (for now).

- Supports one network at a time.

- Embeds as many providers as possible.

- Every prop and parameter is optional.



### What useWallet() is not



- An Ethereum wallet implementation.

- A low-level, fully configurable connection system for Ethereum providers (see [web3-react](https://github.com/NoahZinsmeister/web3-react) if you are after that).

- An general library to interact with Ethereum (see ethers.js, Web3.js, etc.).



### Used by



- [Aragon client](https://github.com/aragon/aragon)

- [Aragon’s Court Dashboard](https://github.com/aragon/court-dashboard)

- [Aragon Voice](https://github.com/vocdoni/bridge-ui/)

- [Wallets Chat](https://app.wallets.chat/)



- _(Your project!)_



## Usage



Add it to your project:



```console

yarn add use-wallet

```



Use it in your React app:



```jsx

// App.js



import React from 'react'

import { useWallet, UseWalletProvider } from 'use-wallet'



function App() {

  const wallet = useWallet()

  const blockNumber = wallet.getBlockNumber()



  return (

    <>

      
Wallet


      {wallet.status === 'connected' ? (

        


          
Account: {wallet.account}


          
Balance: {wallet.balance}


           wallet.reset()}>disconnect

        


      ) : (

        


          Connect:

           wallet.connect()}>MetaMask

           wallet.connect('frame')}>Frame

           wallet.connect('portis')}>Portis

        


      )}

    >

  )

}



// Wrap everything in 

export default () => (

  

    

  

)

```



## API



### <UseWalletProvider />



This is the provider component. It should be placed above any component using `useWallet()`. Apart from `children`, it accepts two other props:



#### chainId



The [Chain ID](https://chainid.network/) supported by the connection. Defaults to 1.



#### connectors



Configuration for the different connectors. If you use a connector that requires a configuration but do not provide one, an error will be thrown.



- `injected`: no configuration needed.

- `frame`: no configuration needed.

- `fortmatic`: `{ apiKey }`

- `portis`: `{ dAppId }`

- `provided`: `{ provider }`

- `authereum`: no configuration needed.

- `squarelink`: `{ clientId, options }`

- `walletconnect`: `{ rpc: { 1: 'https://rpc-url', 3: 'https://rpc-url' } }`

- `walletlink`: `{ url, appName, appLogoUrl }`



See the [web3-react documentation](https://github.com/NoahZinsmeister/web3-react/tree/v6/docs) for more details.



#### autoConnect



Automatically connect to wallet on page load. Defaults to false.



### useWallet()



This is the hook to be used throughout the app.



It takes an optional object as a single param, containing the following:



- `pollBalanceInterval`: the interval used to poll the wallet balance. Defaults to 2000.

- `pollBlockNumberInterval`: the interval used to poll the block number. Defaults to 5000.



It returns an object representing the connected account (“wallet”), containing:



- `account`: the address of the account, or `null` when disconnected.

- `balance`: the balance of the account, in wei.

- `chainId`: The specified Chain ID of the network you're connected to.

- `connect(connectorId)`: call this function with a connector ID to “connect” to a provider (see above for the connectors provided by default).

- `connector`: The "key" of the wallet you're connected to (e.g "metamask", "portis").

- `connectors`: the full list of connectors.

- `error`: contains an error object with the corresponding name and message if `status` is set to `error`.

- `ethereum`: the connected [Ethereum provider](https://eips.ethereum.org/EIPS/eip-1193).

- `getBlockNumber()`: this function returns the current block number. This is a function because the block number updates often, which could trigger as many extra renders. Making an explicit call for the block number allows users of `useWallet()` to avoid extra renders when the block number is not needed.

- `isConnected()`: this function returns whether the wallet is connected.

- `networkName`: a human-readable name corresponding to the Chain ID.

- `reset()`: call this function to “disconnect” from the current provider. This will also clean the latest error value stored in `use-wallet`'s state.

- `status`: contains the current status of the wallet connection. The possible values are:

  - "disconnected": no wallet connected (default state).

  - "connecting": trying to connect to the wallet.

  - "connected": connected to the wallet (i.e. the account is available).

  - "error": a connection error happened.

- `type`: whether or not the account is a contract. Can be `null` when you're

  disconnected, or either `"contract"` or `"normal"`.



## Examples



To run the examples, switch to the respective directories. Then, simply run `yarn install`

to install, and `yarn start` to run the examples on `localhost:1234`.



## Special thanks



useWallet() is a built on [web3-react](https://github.com/NoahZinsmeister/web3-react) and its connectors, which are doing all the hard work internally.