near / wallet-selector

This is a wallet selector modal that allows users to interact with NEAR dApps with a selection of available wallets.

NEAR Wallet Selector

NEAR Wallet Selector makes it easy for users to interact with your dApp by providing an abstraction over various wallets within the NEAR ecosystem:

• My NEAR Wallet - Browser wallet.
• Mintbase Wallet - Browser wallet.
• Bitte Wallet - Browser wallet.
• Ledger - Hardware wallet.
• Sender - Injected wallet.
• Math Wallet - Injected wallet.
• Nightly - Injected wallet.
• Meteor Wallet - Injected wallet.
• Metamask Snap - Injected wallet.
• OKX Wallet - Injected wallet.
• Narwallets - Injected wallet.
• WELLDONE Wallet - Injected wallet.
• Coin98 Wallet - Injected wallet.
• Neth - Injected wallet.
• XDEFI Wallet - Injected wallet.
• Ramper Wallet - Injected wallet.
• Bitget Wallet - Injected wallet.
• Here Wallet - Mobile wallet.
• NearFi Wallet - Mobile wallet.
• Near Mobile Wallet - Mobile Wallet.
• WalletConnect - Bridge wallet.
• Ethereum wallets - Injected wallet.

Preview

React / Next.js and Angular variations of the Guest Book dApp can be found in the examples directory. You can use these to gain a concrete understanding of how to integrate NEAR Wallet Selector into your own dApp.

Installation and Usage

The easiest way to use NEAR Wallet Selector is to install the core package from the NPM registry, some packages may require near-api-js v1.0.0 or above check them at packages

# Using Yarn
yarn add near-api-js

# Using NPM.
npm install near-api-js

# Using Yarn
yarn add @near-wallet-selector/core

# Using NPM.
npm install @near-wallet-selector/core

Next, you'll need to install the wallets you want to support:

# Using Yarn
yarn add \
  @near-wallet-selector/bitget-wallet \
  @near-wallet-selector/my-near-wallet \
  @near-wallet-selector/sender \
  @near-wallet-selector/nearfi \
  @near-wallet-selector/here-wallet \
  @near-wallet-selector/math-wallet \
  @near-wallet-selector/nightly \
  @near-wallet-selector/meteor-wallet \
  @near-wallet-selector/okx-wallet \
  @near-wallet-selector/narwallets \
  @near-wallet-selector/welldone-wallet \
  @near-wallet-selector/near-snap \
  @near-wallet-selector/ledger \
  @near-wallet-selector/wallet-connect \
  @near-wallet-selector/coin98-wallet \
  @near-wallet-selector/neth \
  @near-wallet-selector/xdefi \
  @near-wallet-selector/ramper-wallet \
  @near-wallet-selector/near-mobile-wallet  \
  @near-wallet-selector/bitget-wallet \
  @near-wallet-selector/okx-wallet \
  @near-wallet-selector/mintbase-wallet \
  @near-wallet-selector/bitte-wallet \
  @near-wallet-selector/ethereum-wallets


# Using NPM.
npm install \
  @near-wallet-selector/bitget-wallet \
  @near-wallet-selector/my-near-wallet \
  @near-wallet-selector/sender \
  @near-wallet-selector/nearfi \
  @near-wallet-selector/here-wallet \
  @near-wallet-selector/math-wallet \
  @near-wallet-selector/nightly \
  @near-wallet-selector/meteor-wallet \
  @near-wallet-selector/okx-wallet \
  @near-wallet-selector/narwallets \
  @near-wallet-selector/welldone-wallet \
  @near-wallet-selector/near-snap \
  @near-wallet-selector/ledger \
  @near-wallet-selector/wallet-connect \
  @near-wallet-selector/coin98-wallet \
  @near-wallet-selector/neth \
  @near-wallet-selector/xdefi \
  @near-wallet-selector/ramper-wallet \
  @near-wallet-selector/near-mobile-wallet \
  @near-wallet-selector/bitget-wallet \
  @near-wallet-selector/okx-wallet \
  @near-wallet-selector/mintbase-wallet \
  @near-wallet-selector/bitte-wallet \
  @near-wallet-selector/ethereum-wallets

Optionally, you can install our modal-ui or modal-ui-js package for a pre-built interface that wraps the core API and presents the supported wallets:

# Using Yarn
yarn add @near-wallet-selector/modal-ui

# Using NPM.
npm install @near-wallet-selector/modal-ui

Then in your dApp:

import { setupWalletSelector } from "@near-wallet-selector/core";
import { setupModal } from "@near-wallet-selector/modal-ui";
import { setupBitgetWallet } from "@near-wallet-selector/bitget-wallet";
import { setupMyNearWallet } from "@near-wallet-selector/my-near-wallet";
import { setupSender } from "@near-wallet-selector/sender";
import { setupHereWallet } from "@near-wallet-selector/here-wallet";
import { setupNearSnap } from "@near-wallet-selector/near-snap";
import { setupMathWallet } from "@near-wallet-selector/math-wallet";
import { setupNightly } from "@near-wallet-selector/nightly";
import { setupMeteorWallet } from "@near-wallet-selector/meteor-wallet";
import { setupOkxWallet } from "@near-wallet-selector/okx-wallet";
import { setupNarwallets } from "@near-wallet-selector/narwallets";
import { setupWelldoneWallet } from "@near-wallet-selector/welldone-wallet";
import { setupLedger } from "@near-wallet-selector/ledger";
import { setupWalletConnect } from "@near-wallet-selector/wallet-connect";
import { setupNearFi } from "@near-wallet-selector/nearfi";
import { setupCoin98Wallet } from "@near-wallet-selector/coin98-wallet";
import { setupNeth } from "@near-wallet-selector/neth";
import { setupXDEFI } from "@near-wallet-selector/xdefi";
import { setupRamperWallet } from "@near-wallet-selector/ramper-wallet";
import { setupNearMobileWallet } from "@near-wallet-selector/near-mobile-wallet"; 
import { setupMintbaseWallet } from "@near-wallet-selector/mintbase-wallet"; 
import { setupBitteWallet } from "@near-wallet-selector/bitte-wallet";
import { setupEthereumWallets } from "@near-wallet-selector/ethereum-wallets";

const selector = await setupWalletSelector({
  network: "testnet",
  modules: [
    setupBitgetWallet(),
    setupMyNearWallet(),
    setupSender(),
    setupHereWallet(),
    setupMathWallet(),
    setupNightly(),
    setupMeteorWallet(),
    setupNearSnap(),
    setupOkxWallet(),
    setupNarwallets(),
    setupWelldoneWallet(),
    setupLedger(),
    setupNearFi(),
    setupCoin98Wallet(),
    setupNeth(),
    setupXDEFI(),
    setupWalletConnect({
      projectId: "c4f79cc...",
      metadata: {
        name: "NEAR Wallet Selector",
        description: "Example dApp used by NEAR Wallet Selector",
        url: "https://github.com/near/wallet-selector",
        icons: ["https://avatars.githubusercontent.com/u/37784886"],
      },
    }),
    setupNearMobileWallet(),
    setupMintbaseWallet({
          networkId: "mainnet",
          walletUrl: "https://wallet.mintbase.xyz",
          callbackUrl: "https://www.mywebsite.com",
          deprecated: false,
    }),
    setupBitteWallet({
        networkId: "mainnet",
        walletUrl: "https://wallet.bitte.ai",
        callbackUrl: "https://www.mywebsite.com",
        deprecated: false,
    }),
    setupEthereumWallets({ wagmiConfig, web3Modal }),
  ],
});

const modal = setupModal(selector, {
  contractId: "guest-book.testnet"
});

Wallet Package Documentation

Each wallet package contains its own README document, please refer inside the packages folder for extra information.

Contributing

Contributors may find the examples directory useful as it provides a quick and consistent way to manually test new changes and/or bug fixes.

More details around contributing to this project can be found here.

Editor Setup

This project uses ESLint (with Prettier) to enforce a consistent coding style. It's important that you configure your editor correctly to avoid issues when you're ready to open a Pull Request.

Although this project uses Prettier, it's simply an "internal" dependency to our ESLint configuration. This is because we want Prettier to handle code styling while avoiding conflicts with ESLint which specifically focuses on potentially problematic code. As a result, it's important that you switch off Prettier in your editor and ensure only ESLint is enabled.

License

This repository is distributed under the terms of both the MIT license and the Apache License (Version 2.0). See LICENSE-MIT and LICENSE-APACHE for details.

wallet-selector's Issues

Integrate modal to example dApp for e2e testing

Related to task #17

Restructure classes into injected, wallets and hardware

Related to user story #3

Currently, everything is extended from the BaseWallet class. To add more abstraction the logic needs to be separated into multiple wallet types.

Types:

• injected (browser extensions)
• wallet (redirect/website wallet)
• hardware (ledger)

This is a suggestion from Mike.

Go through LavaMoat toolset documentation

See how to implement and use LavaMoat toolset.

https://github.com/LavaMoat/LavaMoat

Fix Near Wallet signing with attached amount and gas

Currently if you attach an amount and create transaction it does not redirect you to verify transaction it does the transaction like you are not attaching any Near tokens.

Add SenderWallet install message

When the user selects SenderWallet provider option from the modal, if the SenderWallet extension is not detected the message "You'll need to install SenderWallet extension to continue. After installing refresh the page." is shown with the link to redirect to the chrome web store to install it.

Link: chrome web store

Example:

Build and deploy example dApp

As suggested build and deploy new example dApp

https://near-examples.github.io/guest-book

Add the ability to enter a custom derivation path

Related to user story #23

Add the ability to choose from common derivation paths

Related to user story #24

Caching wallet selection of the user

Caching wallet selection of the user so that it can be automatically selected for them the next time they visit dApp for a better user experience and ease of use.

Examples:

https://github.com/Web3Modal/web3modal/blob/master/src/controllers/providers.ts#:~:text=public%20setCachedProvider(id%3A%20string)%20%7B

https://docs.blocknative.com/onboard#:~:text=You%20may%20want%20to%20cache%20the%20wallet%20a%20user%20has%20selected

Add Support for Signing & Sending Transactions

As a dApp user, I WANT to be able to choose the option "connect with Ledger Wallet" from the modal SO THAT I can see different derivation paths to connect my account/s AND have an option to add custom derivation path

Acceptance criteria

GIVEN that I access dApp
WHEN I choose the "connect with Ledger Wallet" option from the modal
THEN the derivation paths and input field are shown in the modal
AND I can add a custom derivation path

Implement the signOut method for Sender Wallet

Related to user story #4

Show "What is a wallet?" explonation in the guest book example

When initializing the wallet selector in the options object pass also the following option (object):

walletSelectorUI: {
  description: "Please select a wallet to connect to this dapp:",
  explanation: `Wallets are used to send, receive, and store digital assets. There are different types of wallets. 
              They can be an extension added to your browser, a hardware device plugged into your computer, 
              web-based, or as an app on your phone.`,
}

Repository: https://github.com/amirsaran3/guest-book-example
Live Demo: https://amirsaran3.github.io/guest-book-example/

With this the collapsible wallet explanation and a custom description will be shown like in the below pic:

Implement basic Ledger (hard wallet) connection demo

Related to user stories #23 and #24

Signing transactions with Ledger wallet provider

Button "Custom Path" changes into Input Field (onClick event)

Related to user story #24

Button "Custom Path" should not be visible after click event and after the input field is shown.

Display wallet providers based on the user's device

Display wallet providers based on the user's device and/or browser type.

Examples:

https://docs.blocknative.com/onboard#:~:text=wallets%20will%20be%20displayed%20when%20a%20user

https://docs.blocknative.com/onboard#:~:text=a%20preferred%20wallet.-,Example,-1

Add Support For Unit Testing

Description

This project is currently lacking ways for changes to be validated. We need a unit testing solution that can inspect functionality in various ways to ensure we don’t:

• Cause regressions as we make further enhancements.
• Validate new features are working as intended (as described in task Acceptance Criteria)

My proposed solution, given we’re using React, is to implement Jest coupled with React Testing Library. These frameworks will provide a foundation for us to move quickly without compromising on quality.

As common practice, we will add Jest to the “test” NPM script. In the future we can look at integrating this command with GitHub Actions to ensure pull requests are in a working state before reviews take place.

Acceptance Criteria

• Jest and React Testing Library are added to the devDependencies list in the package.json
• test NPM script in the package.json file maps to the Jest CLI command (correctly configured with a Jest config file).
• A basic test that simply renders the Modal component passes.

As a dApp user, I WANT to be able to choose the appropriate derivation path shown in the modal SO THAT I can select my Ledger device from the browser pop up AND initiate the connection to that physical device

Acceptance criteria

GIVEN that I access dApp and I have Ledger device connected
WHEN I choose the appropriate derivation path from the modal
THEN the browser pop up is shown with the list of available devices
AND I choose the Ledger device from the list
AND the connection to that physical device is initiated

Go through Narwallet (browser extension wallet) documentation

See if it's possible to initiate a connection to it from the wallet selector modal.

https://github.com/Narwallets/narwallets-extension/blob/master/API-design.md

Encapsulate DOM Mutations in React

Description

As mentioned in #54, we need to move away from mutating the DOM directly, particularly elements owned by React. When React mounts to a given target, it must be the sole owner of the HTML node (and child nodes it contains). This is because in order for React to make necessary changes, it needs to have a representation of what the DOM looks like currently and what the next render should look like. The difference between these two states is what React then batches up into efficient DOM operations. When we directly modify these elements outside of React (in the case of ModalHelper this is, for example, when we change the style of elements), it no longer has a consistent model of what the actual DOM looks like to what it has in memory (Virtual DOM).

Ignoring the bugs that come with this approach, it is also confusing for the project as a whole. We should be able to make the assumption that everything related to the UI is in the React realm and not managed by multiple sources.

My proposed solution is to move away from the ModalHelper entirely and either make a containing React component in its place and/or migrate some of the functionality directly into the Modal component.

Acceptance Criteria

• Direct DOM mutations are removed from the project in favour of using React. This is usually achieved by introducing state of some kind.
• Creation of the modal element is moved into the NearWalletSelector.

Add a collapsible section to the modal UI

Related to user story #2

Add an animated collapsible (slide down) section to the modal with the general description of what is a wallet and what are different types of wallets.

Description to add:

"Wallets are used to send, receive, and store digital assets. There are different types of wallets. They can be an extension added to your browser, a hardware device plugged into your computer, web-based, or as an app on your phone."

Text within Modal is not visible when system is using dark mode with 'light' theme

Description

When the modal is launched with the "theme": "light" configuration, I'm unable to see the text. It seems the text matches the background colour.

Steps to Reproduce

1. Configure system/browser to use dark mode.
2. Configure initialisation options to use the 'light' theme.
3. Launch modal
4. Observe 'invisible' text.

Acceptance Criteria

• Text is clear and visible in any of the following scenarios:
  • Dark mode with 'light' theme.
  • Dark mode with 'dark' theme.
  • Light mode with 'light' theme.
  • Light mode with 'dark' theme.

Create basic, extendable system for various wallet types

As we discussed in our calls, we can model the architecture of OnboardJS and Web3Modal to create a modal pop-up that displays different available NEAR wallets for the end user to choose. The user will then interact with this wallet unless they choose to "deconnect" the wallet, in which has the modal would pop up again when prompted.

The three types of wallets we can start with are:

1. URL Redirect (like NEAR Wallet or the NEAR Wallet for testnet)
2. Hardware wallet (We currently support Ledger. More info on this in our main documentation.)
3. Browser extension (SenderWallet and keep in mind the Opera wallet that's coming, and potentially NarWallets)

Please watch this video that's a cursory review of how OnboardJS is likely the better option to take inspiration from:
https://youtu.be/8pDf_PaxdpY

PS: This is worth a look, to see how another potential web-based wallet may join the ecosystem with a pop-up.
https://youtu.be/AlMlYajqCzM?t=488

Update project's README.md file

Final update to README.md file should contain:

• introduction with a summary paragraph that describes the project at a high level

• simple installation and usage instructions

• a preview of project features with a demo GIF or screenshots

• a list of the functions that will be included in the package (this should be a 1-2 sentence description for each function)

• added license (a short description of the license)

As a dApp user, I WANT to be able to choose the option "connect with Narwallet" from the modal SO THAT Narwallet browser extension window pops up AND so that I can approve the connection between my Narwallet account and dApp

Integrate wallet selector into Guest Book example

The Guest Book example (https://github.com/near-examples/guest-book) currently uses just the Near Wallet for signup and to call smart contracts. We need to change that so that the user has an option to signup and call smart contracts using our near-walletselector modal. Inside the modal will be three options: Near Wallet, Sender Wallet and Ledger Hardware Wallet.

Create a new dev branch

Develop logic for adding new wallet providers as objects

Related to user story #3

As a dApp developer, I WANT to have different options for color schemes of the modal SO THAT I can change it to fit my existing dApp theme

Switch network message

Detect if the user needs to switch wallet provider network if it's not matching the network of dApp and show an appropriate message.

Add an option for the user to switch to a different wallet provider if their selected wallet provider doesn't support changing networks.

Example:

Implement option to connect with NEAR Wallet using near-api-js and WalletConnection

Related to user story #5

Create NPM package using TypeScript

Add switch wallet provider functionality

Have a function that will be called to open a modal again for the user to switch from already selected to a different wallet provider.

Check to see if the wallet provider that the user is selecting is the same as the current one so that it won't instantiate twice.

Show already selected wallet option in the modal. Example:

Research URI / Deep linking approach

Research about deep linking for wallet integration.

near/NEPs#10 (comment)

Example:

If an end-user wants to transfer NEAR, the URI path would be something like:

near-wallet://action/Transfer/10?to=mike.near"

Enhance modal UI

Related to user story #2

Signing multiple transactions with Ledger wallet

Currently when signing a transaction using the Ledger Wallet option it works the first time. To sign the second time you need to logout and log back in. #23

Create an object that defines how the wallet-selector modal will render

Create an object that defines how the wallet-selector modal will render using different parameters.

Example:

https://docs.blocknative.com/onboard#:~:text=A%20object%20that%20defines%20how%20the%20wallet%20select%20screen%20will%20render%20using%20the%20following%20parameters%3A

As a dApp user, I WANT to be able to sign out from dApp SO THAT I can disconnect my wallet account from it

As a dApp user, I WANT to be able to connect after choosing a preferred wallet option from modal SO THAT I can interact with the wallet account until I choose to disconnect it from dApp

Go through Ledger (hardware wallet) documentation

Identify requirements for making a connection with Ledger hard wallet device.

Resources:

https://github.com/near/near-ledger-js

https://docs.near.org/docs/tutorials/ledger

https://blog.neufund.org/integrating-ledger-nanos-into-your-dapp-using-neufunds-js-wallet-provider-ecb71ca8f7b6

https://www.youtube.com/watch?v=V9eRdPCE2lo

https://portal.productboard.com/lnpb6dhpyz225uxhuo74d32p/c/25-support-active-ledger-transports?utm_medium=social&utm_source=portal_share

https://github.com/wandevs/wan-web-wallet/blob/master/src/wallets/ledger.ts

Implement an option for connecting with SenderWallet using requestSignIn method

Related to user story #6

As a dApp user, I WANT to see a modal pop-up in the center of the screen that displays different available NEAR wallets SO THAT I can choose the preferred option to sign-in/connect with dApp

As a dApp user, I WANT to be able to choose the option "connect with NEAR" from the modal SO THAT I can be redirected to web-based NEAR WALLET AND so that I can approve the connection between my NEAR Wallet account and dApp

Migrate Wallet State Into React

Description

I’ve noticed a few major problems with the implementation of state in this project. The main source of state is stored in a “global” (if we ignore the require cache) module here. The problem with this approach is React doesn’t own this object so it’s unable to respond to changes made to it. This leads to inconsistencies in the view layer and the underlying state model.

My proposed solution is to migrate this state object into the React realm either by using a store pattern (using context) or multiple useState hooks directly in a persistently mounted top-level component.

Before this work can commence, we need to address another design problem I’ve identified in the ModalHelper module here. This module needs to move away from modifying DOM elements directly - this is the job of React and can be done more effectively this way. The visibility of the modal and particular sections would become useState variables within the component(s). See #56 for more detail.

Acceptance Criteria

• Changes to state are immediately reflected in the UI.
• State is no longer global. This will technically mean new instances of the wallet selector are encapsulated. However, the idea of multiple wallet selectors needs to be addressed in another ticket - this should not be possible(?).
• References to local storage values should be removed from state. Currently values such as isSignedIn and signedInwalletId are only evaluated when the module is first imported (when NearWalletSelector is imported). Logic that relies on this will be susceptible to out-of-date values which ultimately cause bugs in the long run.

Define Wallet Selector modal style and develop new CSS class for dark mode

Related to user story #2

As a dApp user, I WANT to be able to choose the option "connect with Sender Wallet" from the modal SO THAT Sender Wallet browser extension window pops up AND so that I can approve the connection between my Sender Wallet account and dApp

Move project to wallet-selector repo

Error handling for Ledger wallet provider option

Related to user stories #23 and #24

After selecting the appropriate derivation path to connect if Ledger wallet device is not found and selected from the browser pop up, display error message "Error connecting to Ledger wallet".

Example:

Add account id input when connecting with ledger wallet

When connecting with the Ledger Wallet option before clicking the connect button the user needs to input his account id which will be used to create transactions.