Wallet selection & SDK

This is to outline the issues and potential ideas how to address current issue with wallet usage from applications.


Currently there are two interesting issues with using wallet in apps on NEAR:

  • Almost all application code just directly links to wallet.near.org
  • Application level wallet usage code is split between near-api-js and near-wallet codebases. Many general pieces of code must be copy-pasted (like using Ledger in Web, parsing lockup state and more)

Direct linkage of specific version of web wallet means, that other wallets are hard to impossible to use. There are already options like 2 chrome extensions, mobile wallets and more.

To be more clear, let’s split wallet functionality into few different things:

  • Primary key management: this is where full access or similar is stored, providing recovery and other ways
  • App key management: managing app specific key scoped to limited set of actions
  • Tx signing and routing: given a transaction, signing it and sending it into the network, either directly or via relayers (Using NEAR with Ethereum wallets).

Application devs if they want to support more things primary key management outside of NEAR wallet need to implement their own additional management.

App key management implementation in near-api-js is also pretty limited and missing various functionality.

We also have multiple different ways to route transactions to the network and probably more is coming.

Potential solution

Proposed solution to define a “Wallet SDK” interface which provides an abstractions for the wallet related usage. Implemented in the JS or other language libraries.

First, it is able to ask user which wallet they want to use. The registry of wallets can be some form of smart contract registry. To start managed more centrally via NF but over time will opened up to members of relevant advisory boards.

Hence when user presses Login, there is a menu to select which wallet they want to use (similar exists in Ethereum right now). This menu both can be done on application side or when user gets sent to “wallet.near.org” (I like matrix.org invite selector for this).

Of cause, if user already selected something, that wallet should be used across all the applications by default. While there should be also an option to change (some users will use multiple wallets – especially developers).

There is an important part, which is what Wallet Connect is trying to define - an interface for signing transactions outside of direct HTTPS flow which is impossible with many wallets. Working with their team is important here to have the same protocol for exchanging the relevant information (request id, metadata, etc).

Wallet SDK contains our app level code for managing “App key management”.
This is where the code lives to identify if transaction is under permissions or primary key management must be called. Any additional logic, like managing allowances and more can live here as well.

Additionally, Wallet SDK would contain any relevant relayer code for routing transactions that are meta-signed instead of directly signed. For example this is relevant for Using NEAR with Ethereum wallets and other related work. This is also where RPC discovery should be happening (On-chain discovery service).

Curious what do you think?


I’ll share here what I’m experimenting with right now. It’s WIP, it’s not an answer to the problem, and it’s not even a generic solution. It’s just a trade-off based on certain assumptions I’m making:


  1. I want to support static-server SPA DApps (i.e. can be served from IPFS or siasky). Also I want to not disrupt the SPA state (not leaving the site), that’s why I’m working with a chrome/chromium extension wallet

  2. My “model-user” is not an expert. My user doesn’t want to have to acquire deep knowledge of the underlying technologies to use the application. For my user, both screens of EIP721 are gibberish
    (EIP712 “before and after”. To read/understand/verify the data in the image on the right, you need way more knowledge my model-users have, so both images are gibberish to them. Amounts with that many zeroes are confusing and hard to read and they don’t know what to do with a unix timestamp)

  3. This is what I want my model-user to see when approving transactions:

    example from DApp-diversifying-staking-pool & narwallet

The info here for the user is: what account is currently selected, what web page is connected, what contract the user is going to operate on and what function exactly is going to be called, with all the amounts in NEAR (no yoctos, always easy to read amounts).

  1. I want to ease-up the onboarding of ethereum users. One of the NEAR features more alien to eth users is the fact that an account can have more than one private key. I’m hiding that functionality inside “advanced mode”. In “normal mode”, I’m asking for the seed phrase or a priv-key (full access) and then sign transactions with that, i.e. the wallet is not adding keys to the user’s near account.

What I’m experimenting with right now

I’m doing a kind of “dependency inversion”. Instead of the DApp having a “login” button or several “login” buttons, one for each supported wallet, the connection is initiated by the wallet.

This solves two problems:

  1. Multiple extension wallets: If you have multiple wallets installed, you choose which wallet you want to use to “connect” to the web page. (Here’s an example help page the user is directed to when tries to “login” from the DApp: https://www.narwallets.com/help/connect-to-web-app/. There could be a generic help page directing to each compatible extension-wallet.)

  2. The DApp can be “chain and wallet agnostic”. Since the connection is initiated from the wallet and all access to the chain is made thru wallet-SDK, it’s easier to make a DApp “chain and wallet agnostic”

All access to the chain is made thru wallet-SDK

I’m experimenting with a very-light wallet-SDK for DApps. The Wallet-SDK only has the required code to communicate with a compatible chrome-extension wallet (chrome.runtime.sendMessage, listeners, window.postMessage marshaling). That’s very few lines of code. It does not include json-RPC, crypto, BN, borsh, BIP-39, ed25519, tweetnacl or any other dependency.

The extension-wallet has all those dependencies and its job is to sign transactions and communicate with the chain, hiding all the complexity from the DApp.

Because the wallet-SDK is very simple, it could be possible to create a single DApp that works with different blockchains, depending on what extension-wallet you decide to activate to “connect-to-the-web-page”. The wallet itself handles all the complexity of tx-signing and broadcasting, and the smart contracts are different for each chain, but because the wallet-SDK is simple and high-level, it could “theoretically” be possible to use the same DApp to operate on different chains.

This is all experimental and it’s not finished or completed yet.


Update: The API si completed and working here:


update: The chrome-extension wallet is now in the chrome-store for everyone to use: Narwallets - Chrome Web Store


Using Math Wallet Near JS API
For Math Wallet DAPP Developer


I’ve created a github org to support the wallet-selection & wallet-provider standardisation wallet-provider-js · GitHub

Please ask to be added so we can build a common interface usable by all stakeholders

The objective is to design a wallet-selection library to be used by DApps, and a standard wallet-provider-interface supporting all wallets.

Each team could later develop their wallet-provider implementing the wallet-provider-interface

To all stakeholders in the Wallet-SDK group, please comment here: Welcome to wallet-provider-interface Discussions! · Discussion #1 · wallet-provider-js/wallet-provider-interface · GitHub so we can add you to the github org.