Summary
- Wallets are just wrappers around a keypair, but they're essential for secure key management
- Mobile and Web dApps handle their wallet-app connection differently
- MWA handles all of its wallet interaction by wrapping all the wallet's
functionalities within the
transact
function for easier integration. - Solana Mobile's
walletlib
does the heavy lifting for surfacing wallet requests to wallet apps
Lesson
Wallets exist to protect your secret keys. While some applications might have app-specific keys, many blockchain use cases rely on a single identity used across multiple apps. In these cases, you very much want to be careful about how you expose signing across these apps. You don't want to share your secret key with all of them, which means you need a standard for allowing apps to submit transactions for signature to a secure wallet app that holds your secret key. This is where the Mobile Wallet Adapter (MWA) comes in. It's the transport layer to connect your mobile dApps to your wallet.
What is MWA
Mobile Wallet Adapter (MWA) is the mobile connection between dApps and wallets. Much like the wallet adapter we're used to on the web, MWA allows us to create native mobile dApps. However, since the web and mobile are different platforms, we have to approach the app-wallet connection differently.
At its core, a wallet app is fairly straightforward. It's a secure wrapper around your keypair. External applications can request that the wallet sign transactions without ever having access to your secret key. Both the web and mobile wallet adapters define this interaction for their respective platforms.
How does a web wallet work?
A web wallet is simply a browser extension that stores keypairs and allows the browser to request access to its functions. It's the wallet's job to follow the wallet standard, which defines what functions should be available to the browser:
registerWallet
getWallets
signAndSendTransaction
signIn
signTransaction
signMessage
These functions are all available to the browser through the global window
object. The browser extension registers itself as a wallet. The wallet adapter
looks for these registered wallets and allows the client to connect and interact
with them.
A browser extension wallet can run isolated JavaScript. This means it can inject
functions into the browser's window
object. Effectively, the transport layer
here is just extra JavaScript code as far as the browser is concerned.
If you're curious to know more about how browser extensions work, take a look at some open-source browser extensions.
How MWA is different from web wallets
Mobile Wallet Adapter (MWA) is different. In the web world, we just need to
inject some code into the window
object to access our wallets. Mobile apps,
however, are sandboxed. This means that the code for each app is isolated from
other apps. There's no shared state between apps that would be analogous to a
browser's window
object. This poses a problem for wallet signing since a
mobile wallet and a mobile dApp exist in isolated environments.
However, there are ways to facilitate communication if you're willing to get
creative. On Android, basic inter-app communication is done through
Intents
. An
Android Intent is a messaging object used to request an action from another app
component.
This particular communication is one-way, whereas the interface for wallet functionality requires two-way communication. MWA gets around this by using an intent from the requesting app to trigger the wallet app opening up two-way communication using WebSockets.
The rest of this lesson will focus on the MWA interface and functionality rather than the low-level mechanisms underpinning inter-app communication. However, if you want to know the nitty gritty, read the MWA specs.
How to work with MWA
The differences between MWA and the traditional wallet adapter require slight modifications to how you program your apps.
Connect to a wallet
By way of comparison, look at the example of connecting to a wallet with React vs with React Native.
On the web, you wrap the application with WalletProvider
, and then children
access the wallet through the useWallet
hook. From there, children can view,
select, connect, and interact with wallets.
In React Native, using MWA, this looks a little different. In this case,
providers aren't needed. Rather, wallet context is provided through the
transact
function from the MWA package. Behind the scenes, this function
searches the devices for active Solana wallets. It surfaces these wallets to the
user through a partial selection modal. Once the user selects a wallet, that
wallet is provided as an argument to the transact
callback. Your code can then
interact with the wallet directly.
Authorize a wallet
On the web, the first time you connect a wallet to a site in your browser, the wallet prompts you to authorize the site. Similarly, on mobile, the requesting app needs to be authorized before it can request privileged methods like signing a transaction.
Your code can trigger this authorization process by calling
wallet.authorize()
. The user will be prompted to accept or reject the
authorization request. The returned AuthorizationResult
will indicate the
user's acceptance or rejection. If accepted, this result object provides you
with the user's account as well as an auth_token
you can use in
wallet.reauthorize()
for subsequent calls. This auth token ensures that other
apps can't pretend to be your app. The auth token is generated during the
authorize()
call, and subsequent requests from the dApp can use the
reauthorize()
method with the stored token to maintain secure communication
without repeatedly prompting the user.
It's worth noting that all methods except authorize
and deauthorize
are
privileged methods. So you'll want to track if a wallet is authorized or not
and call wallet.reauthorize()
when it is. Below is a simple example that
tracks the authorization state:
Note that the above example does not handle errors or user rejections. In
production, it's a good idea to wrap the authorization state and methods with a
custom useAuthorization
hook. For reference, we built this
in the previous lesson.
Interact with a wallet
Unlike connecting and authorizing wallets, requesting methods like
signAndSendTransactions
, signMessages
, and signTransactions
is virtually
the same between web and mobile.
On the web, you can access these methods with the useWallet
hook. You just
have to make sure you're connected before calling them:
For MWA, simply call the functions on the wallet
context provided by the
transact
callback:
Every time you want to call these methods, you will have to call
wallet.authorize()
or wallet.reauthorize()
.
When invoking wallet.signAndSendTransactions(...)
, it's essential to handle
transaction failures gracefully. Transactions can fail due to various reasons
such as network issues, signature mismatches, or insufficient funds. Proper
error handling ensures a smooth user experience, even when the transaction
process encounters issues:
And that's it! You should have enough information to get started. The Solana mobile team has put in a lot of work to make the development experience as seamless as possible between the two.
What MWA is doing wallet-side
This lesson has talked mostly about what MWA is doing in dApps, but a huge portion of MWA functionality happens in wallets. Whether you want to create your own wallet or simply understand the system better, it's worth discussing what MWA-compatible wallets are doing at a high level. For most readers, it's not essential to feel like you can create a wallet after reading through these sections; simply try to get a sense of the overall flow.
Introduction to the walletlib
Solana Mobile has done the vast majority of the heavy lifting by creating the
mobile-wallet-adapter-walletlib
. This library handles all the low-level
communication between dApps and wallets:
This package is still in alpha and is not production ready. However, the API is stable and will not change drastically, so you can begin integration with your wallet.
However, walletlib
doesn't provide UI for you or determine the outcome of
requests. Rather, it exposes a hook allowing the wallet code to receive and
resolve requests. The wallet developer is responsible for displaying the
appropriate UI, managing the wallet behavior, and appropriately resolving each
request.
How wallets use the walletlib
At its core, wallets use walletlib
by calling a single function:
useMobileWalletAdapterSession
. When calling this function, wallets provide the
following:
- The wallet name
- A configuration object of type
MobileWalletAdapterConfig
- A handler for requests
- A handler for sessions
Below is an example component that shows the scaffold of how wallets connect to
the walletlib
:
If you were to create your own wallet, you would modify the config
object and
implement the handleRequest
and handleSessionEvent
handlers accordingly.
While all of these are required and all are important, the primary element is
the request handler. This is where wallets provide the implementation logic for
each request, e.g. how to handle when a dApp requests authorization or requests
that the wallet sign and send a transaction.
For example, if the request is of type
MWARequestType.SignAndSendTransactionsRequest
, then your code would use the
user's secret key to sign the transaction provided by the request, send the
request to an RPC provider, and then respond to the requesting dApp using a
resolve
function.
The resolve
function simply tells the dApp what happened and closes the
session. The resolve
function takes two arguments: request
and response
.
The types of request
and response
are different depending on what the
original request was. So in the example of
MWARequestType.SignAndSendTransactionsRequest
, you would use the following
resolve function:
The SignAndSendTransactionsResponse
type is defined as follows:
Which response you send would depend on the result of attempting to sign and send the transaction.
You can dig into the
walletlib
source
if you'd like to know all of the types associated with resolve
.
One final point is that the component used for interacting with walletlib
also
needs to be registered in the app's index.js
as the MWA entry point for the
app.
Conclusion
While the MWA is slightly different than the web wallet standard, once you understand the nuances between them it becomes fairly straightforward to implement mobile wallet interaction. This becomes especially true when you understand what MWA is doing not only in your dApp but also in wallets. If anything remains unclear to you, be sure to spend time familiarizing yourself with both sides of the equation.
Lab
Now let's do some hands-on practice by building a mobile wallet. The goal here is to see what happens on both sides of the MWA process to demystify the app-wallet relationship.
0. Set up development environment if needed
Before we start programming our wallet, we need to do some setup. You will need a React Native development environment and a Solana dApp to test on. If you have completed the Introduction to Solana Mobile lab, both of these requirements should be met and the counter app installed on your Android device/emulator.
If you haven't completed/done the intro to solana mobile you will need to:
- Setup an Android React Native developer environment with a device or emulator
- Install a Devnet Solana dApp by doing the following steps in your terminal:
1. Planning out the app's structure
We are making the wallet from scratch, so let's look at our major building blocks.
First, we'll make the actual wallet app (popup not included). This will include:
- Creating a
WalletProvider.tsx
- Modifying the
MainScreen.tsx
- Modifying
App.tsx
Next, we'll make a boilerplate MWA app that displays 'Im a Wallet' anytime the wallet is requested from a different dApp. This will include:
- Creating a
MWAApp.tsx
- Modifying
index.js
Then we'll set up all of our UI and request routing. This will mean:
- Modifying the
MWAApp.tsx
- Creating a
ButtonGroup.tsx
- Creating a
AppInfo.tsx
Finally, we'll implement two actual request functions, authorize and sign and send transactions. This entails creating the following:
AuthorizeDappRequestScreen.tsx
SignAndSendTransactionScreen.tsx
2. Scaffold the Wallet app
Let's scaffold the app with:
Now, let's install our dependencies. These are the same dependencies from our Introduction to Solana Mobile lab with two additions:
@react-native-async-storage/async-storage
: provides access to on-device storagefast-text-encoding
: a polyfill for text encoding
We will be using async-storage
to store our keypair so that the wallet will
stay persistent through multiple sessions. It is important to note that
async-storage
is NOT a safe place to keep your keys in production.
Again, DO NOT use this in production. Instead, take a look at
Android's keystore system.
Install these dependencies with the following command:
We need to depend on Solana's mobile-wallet-adapter-walletlib
package, which
handles all of the low-level communication.
Note: A reminder that this package is still in alpha and is not production ready. However, the API is stable and will not change drastically, so you can begin integration with your wallet.
Let's install the package in a new folder lib
:
Next, in android/build.gradle
, change the minSdkVersion
to version 23
.
Finally, finish the initial setup by building the app. You should get the default React Native app showing up on your device./environment-setup?os=linux&platform=android&guide=native#jdk-studio
If you get any errors make sure you double-check you've followed all of the steps above.
3. Create the main wallet app
There are two parts to the wallet application we'll be building:
- The UI to be displayed when you manually open the wallet application
- The UI to be displayed as a bottom sheet when a separate app requests to use the wallet
Throughout this lab, we'll be calling these the "main wallet app" and "wallet popup," respectively.
- Generate a
Keypair
when the app first loads - Display the address and Devnet SOL balance
- Allow users to airdrop some Devnet SOL to their wallet
This can all be accomplished by creating two files:
WalletProvider.tsx
- Generates a Keypair and stores it inasync-storage
, then fetches the keypair on subsequent sessions. It also provides the SolanaConnection
MainScreen.tsx
- Shows the wallet, its balance, and an airdrop button
Let's start with the WalletProvider.tsx
. This file will use async-storage
to
store a base58 encoded version of a Keypair
. The provider will check the
storage key of @my_fake_wallet_keypair_key
. If nothing returns, then the
provider should generate and store a keypair. The WalletProvider
will then
return its context including the wallet
and connection
. The rest of the app
can access this context using the useWallet()
hook.
AGAIN, async storage is not fit to store secret keys in production. Please use something like Android's keystore system.
Let's create the WalletProvider.tsx
within a new directory named components
:
Note that we are defaulting our rpcUrl
to Devnet.
Now let's make the MainScreen.tsx
. It should simply grab the wallet
and
connection
from useWallet()
, and then display the address and balance.
Additionally, since all transactions require a transaction fee in SOL, we'll
also include an airdrop button.
Create a new directory called screens
and a new file called MainScreen.tsx
inside of it:
Lastly, let's edit the App.tsx
file to complete the 'app' section of our
wallet:
Make sure everything is working by building and deploying:
4. Create helper components
Now let's take a brief detour and create some helper UI components that we'll
need for the wallet popup. We'll define a layout for some text with
AppInfo.tsx
and some buttons in ButtonGroup.tsx
.
First, AppInfo.tsx
will show us relevant information coming from the dApp
requesting a wallet connection. Go ahead and create the following as
components/AppInfo.tsx
:
Second, let's create a component that groups an "accept" and "reject" button as
components/ButtonGroup.tsx
:
5. Create the wallet popup boilerplate
The wallet popup is what is seen when a Solana dApp sends out an intent for
solana-wallet://
. Our wallet will listen for this, establish a connection, and
render the popup.
Fortunately, we don't have to implement anything low-level. Solana has done the
hard work for us in the mobile-wallet-adapter-walletlib
library. All we have
to do is create the view and handle the requests.
Let's start with the absolute bare bones of the popup. All it will do is pop up when a dApp connects to it and simply say "I'm a wallet".
To make this pop up when a Solana dApp requests access, we'll need the
useMobileWalletAdapterSession
from the walletlib
. This requires four things:
walletName
- the name of the walletconfig
- some simple wallet configurations of typeMobileWalletAdapterConfig
handleRequest
- a callback function to handle requests from the dApphandleSessionEvent
- a callback function to handle session events
Here is an example of the minimum setup to satisfy
useMobileWalletAdapterSession
:
We will be implementing handleRequest
and handleSessionEvent
soon, but let's
make the bare-bones popup work first.
Create a new file in the root of your project called MWAApp.tsx
:
The last thing we need to do is to register our MWA app as an entry point in
index.js
under the name MobileWalletAdapterEntrypoint
.
Change index.js
to reflect the following:
Go ahead and test this out to make sure it works. First
Open your Devnet Solana dApp, ideally the counter
app from the previous
lesson, then make a request.
You should see a sheet present from the bottom of the screen that says "I'm a wallet."
6. Create the MWA scaffolding
Let's flesh out MWAApp.tsx
to scaffold out some of the architecture that will
later allow users to connect, sign, and send transactions. For now, we'll only
do this for two of the MWA functions: authorize
and signAndSendTransaction
.
To start, we'll add a few things in MWAApp.tsx
:
- Do some lifecycle management by saving the
currentRequest
andcurrentSession
in auseState
. This will allow us to track the life cycle of a connection. - Add a
hardwareBackPress
listener in auseEffect
to gracefully handle closing out the popup. This should callresolve
withMWARequestFailReason.UserDeclined
. - Listen for a
SessionTerminatedEvent
in auseEffect
to close out the popup. This should callexitApp
on theBackHandler
. We'll be doing this in a helper function to keep functionality contained. - Listen for a
ReauthorizeDappRequest
request type in auseEffect
and automatically resolve it. - Render appropriate content for the different types of requests with
renderRequest()
. This should be aswitch
statement that will route to different UI based on the request type.
Change your MWAApp.tsx
to reflect the following:
Note that renderRequest
is not rendering anything useful yet. We still need to
handle the different requests.
7. Implement the authorization popup
Let's put together our first screen to handle new authorizations. This screen's
only job is to show what app wants authorization and allow the user to accept or
deny the request using the resolve
function from the walletlib
.
We'll use our AppInfo
and ButtonGroup
to compose our entire UI here. All we
have to do is plug in the right information and write the logic for accepting
and rejecting the request.
For authorization, the resolve
function we'll use is the one using the
AuthorizeDappRequest
and AuthorizeDappResponse
types.
AuthorizeDappResponse
is a union of types AuthorizeDappCompleteResponse
and
UserDeclinedResponse
. The definition for each is shown below:
Our logic will determine which of these to use when resolving the request.
Now that we have all that context, we can put everything together in a new file
called screens/AuthorizeDappRequestScreen.tsx
:
Now let's update our MWAApp.tsx
to handle this situation by adding to our
renderRequest
switch statement:
Feel free to build and run the wallet again. When you first interact with another Solana app, our new authorization screen will now appear.
8. Implement the sign-and-send popup
Let's finish up our wallet app with the sign and send transaction screen. Here,
we need to grab the transactions from the request
, sign them with our secret
key from our WalletProvider
, and then send them to an RPC.
The UI will look very similar to our authorization page. We'll provide some info
about the app with AppInfo
and some buttons with ButtonGroup
. This time, we
will fulfill the SignAndSendTransactionsRequest
and
SignAndSendTransactionsResponse
for our resolve
function.
More specifically, we'll have to adhere to what
SignAndSendTransactionsResponse
is unioned with:
We are only going to cover the SignAndSendTransactionsCompleteResponse
,
InvalidSignaturesResponse
, and UserDeclinedResponse
.
Most notably, we'll have to adhere to InvalidSignaturesResponse
:
The InvalidSignaturesResponse
is unique because it requires an array of
booleans, each of which corresponds to a failed transaction. So we'll have to
keep track of that.
As for signing and sending, we'll have to do some work. Since we are sending transactions over sockets, the transaction data is serialized into bytes. We'll have to deserialize the transactions before we sign them.
We can do this in two functions:
signTransactionPayloads
: returns the signed transactions along with a 1-to-1valid
boolean array. We'll check that to see if a signature has failed.sendSignedTransactions
: takes the signed transactions and sends them out to the RPC. Similarly, it keeps an array ofvalid
booleans to know which transactions failed.
Let's put that all together in a new file called
screens/SignAndSendTransactionScreen.tsx
:
Finally, let's edit MWAApp.tsx
and add our new screen to the switch statement:
Go ahead and build and run your wallet app. You should now be able to authorize
your dApp and sign and send transactions. Note that we left
SignMessagesRequest
and SignTransactionsRequest
empty so you can do it in
the Challenge.
Nice work! Creating a wallet, even a "fake" version, is no small feat. If you
got stuck anywhere, make sure to go back through it until you understand what's
happening. Also, feel free to look through the lab's
solution code on the main
branch.
Challenge
Now it's your turn to practice independently. Try and implement the last two
request types: SignMessagesRequest
and SignTransactionsRequest
.
Try to do this without help as it's great practice, but if you get stuck, check out the solution code on the repo.
Push your code to GitHub and tell us what you thought of this lesson!