MWA Typescript Reference (Legacy)

Connect to wallet apps and sign transactions and messages with the Mobile Wallet Adapter API.

API Reference

caution

This document references than older version of the Mobile Wallet Adapter protocol. Although the SDK and wallet apps are backwards compatible, it is recommended for dApps to use the new API.

Install dependencies

• @solana-mobile/mobile-wallet-adapter-protocol

  • Base library that implements the MWA client. Include this, but only import transact from the wrapper library.

• @solana-mobile/mobile-wallet-adapter-protocol-web3js

  • A convenience wrapper for the base library that enables with web3.js primitives like Transaction.

yarn

yarn add \
  @solana-mobile/mobile-wallet-adapter-protocol-web3js \
  @solana-mobile/mobile-wallet-adapter-protocol \

npm

npm install \
  @solana-mobile/mobile-wallet-adapter-protocol-web3js \
  @solana-mobile/mobile-wallet-adapter-protocol \

Import into a file

import {
  transact,
  Web3MobileWallet,
} from "@solana-mobile/mobile-wallet-adapter-protocol-web3js";

Mobile Wallet API Methods

Reference for the Mobile Wallet API for dApps to connect to wallets and receive signing services.

transact

This is the first step in using the Mobile Wallet API.

Starts a Mobile Wallet Adapter session with a locally installed MWA-compatible wallet.

Parameters:

callback: (wallet: Web3MobileWallet) => TReturn required

A callback triggered after session establishment, in which the dApp can issue MWA requests to the wallet app, using the wallet object.

config: WalletAssociationConfig optional

Configuration object containing the following fields:

baseUri string optional

URI used for custom wallet association.

Details

As per spec, during session establishment, the wallet may return a custom URI scheme to use for future session establishments. The dApp can choose to use this custom URI by suppyling it through this parameter.

Result:

The result will be a Promise<TReturn> with TReturn equal to what is returned from the callback parameter.

Code sample:

const result = await transact(async (wallet: Web3MobileWallet) => {
    /* ...Issue MWA requests... */
    return "done";
});

Return:

console.log(result) // "done"

Web3MobileWallet.authorize

Non-privileged method. Requests authorization from the connected wallet for access to privileged methods within the session.

Parameters:

cluster: string required

The Solana network cluster with which the dapp intends to interact; supported values include "mainnet-beta", "testnet", "devnet".

identity: object optional

A JSON object containing the following fields:

uri string optional

A URI representing the web address associated with the dapp making this authorization request. If present, it must be an absolute, hierarchical URI.

icon string optional

A relative path (from uri) to an image asset file of an icon identifying the dapp making this authorization request.

name string optional

the display name for this dapp.

Result:

The result will be a JSON object containing the following fields:

• auth_token: string - A string representing a unique identifying token issued by the wallet to the dapp. Use this on future connections to reauthorize access to privileged methods.
• accounts - one or more value objects that represent the accounts to which this auth token corresponds. These objects hold the following properties:
  • address: string - a base64-encoded address for this account.
  • label: string (optional) - a human-readable string that describes the account.
  • wallet_uri_base: string (optional) - A custom URI specified by the wallet that the dapp should use for subsequent connections.

Code sample:

const result = await transact(async (wallet: Web3MobileWallet) => {
    const authResult = wallet.authorize({
      cluster: 'devnet',
      identity: {
        name: 'Example dApp',
        uri:  'https://yourdapp.com'
        icon: "favicon.ico", // Resolves to https://yourdapp.com/favicon.ico
      },
    }));
    return authResult;
});

Result:

{
  "auth_token": "<auth_token>",
  "accounts": [
      {"address": "<address>", "label": "<label>"},
      ...
  ],
  "wallet_uri_base": "<wallet_uri_base>",
}

Web3MobileWallet.reauthorize

Non-privileged method. Like authorize, this method attempts to put the current session in an authorized state, but provides a previously issued auth_token. The session is authorized with the privileges associated with the specified auth_token.

Parameters:

auth_token: string required

A string representing a unique identifying token previously issued by the wallet to the dapp.

identity: object optional

A JSON object containing the following fields:

uri string optional

A URI representing the web address associated with the dapp making this authorization request. If present, it must be an absolute, hierarchical URI.

icon string optional

A relative path (from uri) to an image asset file of an icon identifying the dapp making this authorization request.

name string optional

the display name for this dapp.

Result:

The result will be a JSON object as defined in authorize, but the values may be updated and differ from the values originally provided in the authorize response for the auth token.

• auth_token: string - a string representing a unique identifying token issued by the wallet to the dapp.
• accounts - one or more value objects that represent the accounts to which this auth token corresponds. These objects hold the following properties:
  • address: string - a base64-encoded address for this account.
  • label: string (optional) - a human-readable string that describes the account.
  • wallet_uri_base: string (optional) - A custom URI specified by the wallet that the dapp should use for subsequent connections.

Code sample:

const result = await transact(async (wallet: Web3MobileWallet) => {
  const authResult = wallet.reauthorize({
    auth_token: '<previously_stored_auth_token>'
    identity: {
      name: 'Example dApp',
      uri:  'https://yourdapp.com'
      icon: "favicon.ico", // Resolves to https://yourdapp.com/favicon.ico
    },
  }));
  return authResult;
});

Result:

{
  "auth_token": "<auth_token>",
  "accounts": [
      {"address": "<address>", "label": "<label>"},
      ...
  ],
  "wallet_uri_base": "<wallet_uri_base>",
}

Web3MobileWallet.deauthorize

Non-privileged method. This method will make the provided auth_token invalid for use (if it ever was valid).

If, during the current session, the specified auth token was returned by the most recent call to authorize or reauthorize, the session will be placed into the unauthorized state.

Parameters:

auth_token: string required

An auth token string previously returned by a call to authorize, reauthorize, or clone_authorization, which will be deauthorized.

Result:

The result will be an empty JSON object.

Code sample:

const result = await transact(async (wallet: Web3MobileWallet) => {
  const authToken = getPreviouslyStoredAuthToken()
  return await wallet.deauthorize({auth_token: authToken});
});

Result:

{}

Web3MobileWallet.getCapabilities

Non-privileged method. This method enumerates the capabilities and limits of the wallet's MWA implementation.

Parameters:

None

Result:

The result will be a JSON object as defined in authorize, but the values may be updated and differ from the values originally provided in the authorize response for the auth token.

• supports_clone_authorization: true if the clone_authorization method is supported, otherwise false
• supports_sign_and_send_transactions: true if the sign_and_send_transactions method is supported, otherwise false
• max_transactions_per_request: (optional) if present, the max number of transaction payloads which can be signed by a single sign_transactions or sign_and_send_transactions request. If absent, the implementation doesn’t publish a specific limit for this parameter.
• max_messages_per_request: (optional) if present, the max number of transaction payloads which can be signed by a single sign_messages request. If absent, the implementation doesn’t publish a specific limit for this parameter.
• supported_transaction_versions: the Solana network transaction formats supported by this wallet endpoint. Allowed values are those defined for TransactionVersion (for e.g., "legacy", 0, etc).

Code sample:

const result = await transact(async (wallet: Web3MobileWallet) => {
  const capabilities = await wallet.getCapabilities();
  return capabilities;
});

Result:

{
  "supports_clone_authorization": false,
  "supports_sign_and_send_transactions": true,
  "max_transactions_per_request": 20,
  "max_messages_per_request": 15,
  "supported_transaction_versions": ["legacy", 0]
}

Web3MobileWallet.signTransactions

Privileged method. Request to sign the given transactions with the private keys for the requested authorized account.

Parameters:

transactions: Transaction[] required

An array of one or more transactions to sign. The transaction are of type Transaction or VersionedTransaction from the web3.js library.

Result:

• Transaction[] - the corresponding Transactions signed with the private keys for the requested authorized account addresses.

Code sample:

const result = await transact(async (wallet: Web3MobileWallet) => {
  const authResult = await wallet.authorize({
    cluster: 'devnet',
    identity: APP_IDENTITY,
  }));
  
  const publicKey = getPublicKeyFromAuth(authResult)

  // Create a web3.js Transaction that transfers
  // lamports to a randomly created address.
  const keypair = Keypair.generate();
  const randomTransferTransaction = new Transaction({
    ...latestBlockhash,
    feePayer: publicKey,
  }).add(
    SystemProgram.transfer({
      fromPubkey: publicKey,
      toPubkey: keypair.publicKey,
      lamports: 1_000,
    }),
  );

  // Signs the Transactions with the private key of the account 
  // corresponding to `publicKey`
  const signedTransactions = await wallet.signTransactions({
        transactions: [randomTransferTransaction],
  });
  return signedTransactions;
});

Result:

[<signed_transaction>, ...],

Web3MobileWallet.signAndSendTransactions

Privileged method. This method is optional for the wallet to support.

This method requests the wallet to sign the specified transactions with the private keys for the authorized addresses, submit the transactions to the network, and return the transaction signatures to the dapp.

Parameters:

transactions: Transaction[] required

An array of one or more transactions to sign and send. The transaction are of type Transaction or VersionedTransaction from the web3.js library.

minContextSlot: number

The minimum slot number at which to perform preflight transaction checks.

Result:

• string[] - the corresponding base64-encoded transaction signatures.

Code sample:

const result = await transact(async (wallet: Web3MobileWallet) => {
  const authResult = await wallet.authorize({
    cluster: 'devnet',
    identity: APP_IDENTITY,
  }));
  
  const publicKey = getPublicKeyFromAuth(authResult)

  // Create a web3.js Transaction that transfers
  // lamports to a randomly created address.
  const keypair = Keypair.generate();
  const randomTransferTransaction = new Transaction({
    ...latestBlockhash,
    feePayer: publicKey,
  }).add(
    SystemProgram.transfer({
      fromPubkey: publicKey,
      toPubkey: keypair.publicKey,
      lamports: 1_000,
    }),
  );

  // Signs the Transactions with the private key of the account 
  // corresponding to `publicKey` and submits to the network.
  const transactionSignatures = await wallet.signAndSendTransactions({
    transactions: [randomTransferTransaction],
  });
  return transactionSignatures;
});

Result:

["<transaction_signature>", ...],

Web3MobileWallet.signMessages

Privileged method. Request to sign the given messages with the private keys for the requested authorized account.

Parameters:

addresses: string[] required

One or more base64-encoded addresses of the accounts which should be used to sign message. These should be a subset of the addresses returned by authorize or reauthorize for the current session's authorization.

payloads: Uint8Array[] required

One or more byte arrays where each byte array is a message payload to sign.

Result:

• Uint8Array[] - the corresponding base64-encoded signed message payloads.

Code sample:

 const result = return await transact(async (wallet: Web3MobileWallet) => {
  // First, request for authorization from the wallet.
  const authorizationResult = await authorizeSession(wallet);

  // Construct a message byte array
  const message = 'Hello world!';
  const messageBuffer = new Uint8Array(
    message.split('').map(c => c.charCodeAt(0)),
  );

  // Sign the payload with the provided address from authorization.
  const signedMessages = await wallet.signMessages({
    addresses: [authorizationResult.address],
    payloads: [messageBuffer],
  });

  return signedMessages;
});

Result:

[<signed_messages>, ...],