The goal: Users should always have the option to use their mobile wallet -- no matter where their dApp is running.

For example, it should be possible to run a dApp on a desktop computer (even one that isn't yours) and still be able to safely interact with it.

For the user, this means that they can store their keys safely in their mobile wallet. It is also more convenient since it e.g. allows you to manage a dApp on a larger monitor.

Watch video

NFT Demo

Project's website

The core component of Solana MobileConnect is a session server that manages login and transaction sessions. It does most of the heavy lifting.

Here's the flow of a transaction initiated by the user:

The frontend serializes the transaction and sends it to the server to create a new transaction session. The transaction is now accessible via the unique ID of the session. On the frontend, this unique link is encoded in a QR code and displayed to the user. Once the user scans it, they will receive the transaction (using Solana Pay's Transaction Requests). They sign it and it is broadcast to the network.

The frontend polls the state of the transaction session, which prompts the server to check the state of the blockchain.

After a while, the transaction will have reached the confirmed state. This will be reflected in the state of the transaction session returned by the server. The frontend can now notify the user.

To log in, the frontend creates a new login session on the server.

Each login session is associated with a unique link, which is encoded in a QR code.

When the user scans it, their public key is sent to the server (according to Solana Pay's Transaction Requests), allowing the server to capture and associate it with the login session.

Meanwhile, the frontend polls the server for the login session and eventually receives the public key. This is when the user is logged in.

Note that, when the user scans the QR code, the server sends back a dummy transaction and ignores it afterwards -- since we're only interested in the public key.

The role of the wallet adapter is to be an intermediary between frontend and session server. For example, when the frontend code makes a sendTransaction request, the wallet adapter creates a new transaction session on the server, displays the QR code to the user and handles the polling.

A browser extension would require the user to install yet another extension -- on every device and for a single use case. It's not an ideal user experience.

WalletConnect is a lot more complicated to set up for developers. It also uses websockets, which tend to be more fragile. It also takes some time to set up a persistent connection, while MobileConnect instantly generates a QR code.

With MobileConnect, we have a relatively simple setup for developers, a great UX (users can use it right out of the box without installing anything). This is mostly achieved by leveraging already existing technologies -- especially Solana Pay.

You first have to decide which session server you want to use. If a public server is sufficient for your use case (e.g. for testing), you can skip this step. If you want to set up your own server, you can clone this repository and set it up accordingly.

Now, you need to integrate MobileConnect's wallet adapter into your dApp.

Run npm install solana-mobileconnect-wallet-adapter to install the package.

You include it like any other wallet adapter:

import { MobileConnectWalletAdapter } from 'solana-mobileconnect-wallet-adapter'

const WalletContextProvider: FC<{ children: ReactNode }> = ({ children }) => {
    const wallets = [
      new MobileConnectWalletAdapter(),
    ]
}

If you use a private server, you must also pass its URL: new MobileConnectWalletAdapter("your-server.com")

Uniqueness of Transactions: In the current implementation, the developer must ensure that the instruction set of transactions is unique. This has to do with how the server tracks transactions on the blockchain.

Example: a simple transfer app that allows the user to send SOL to an arbitrary recipient. It may be that a user sends the same amount twice to the same recipient (this results in two transactions with the same instruction set). For this app to work with MobileConnect, the developer needs to ensure uniqueness of transactions. An easy way to achieve that is by adding a memo instruction with random data to each transaction.

Security of Login: In the current implementation, users are logged in by simply sending their public key to an endpoint. In principle, anyone could log in with any public key. Until message signing is implemented, the authenticity of a user cannot be guaranteed. Please don't show sensitive data based on the active wallet.

Only base function are implemented: The wallet adapter allows a user to connect and sendTransaction remotely. However, signTransaction, signAllTransactions and signMessage are not supported because of technical limitations.