MetaMask

MetaMask is a mobile wallet that provides easy access to websites that use the Ethereum blockchain.

For up to the minute news, follow our Twitter or Medium pages.

To learn how to develop MetaMask-compatible applications, visit our Developer Docs.

MetaMask Mobile

Environment Setup

The code is built using React-Native and running code locally requires a Mac or Linux OS.

• Install sentry-cli tools: brew install getsentry/tools/sentry-cli

• Install Node.js version 16

  • If you are using nvm (recommended) running nvm use will automatically choose the right node version for you.

• Install Yarn v1

• Install the shared React Native dependencies (React Native CLI, not Expo CLI)

  • XCode version 14.2 or below

• Install cocoapods by running:

sudo gem install cocoapods -v 1.12.1

• Install Python version ^3.10
  • Note: M1 User might need to stay with version 3.10

Device Environment Setup

Android

• Install Java. To check if Java is already installed, run:

  java -version

• Install the Android SDK, via Android Studio.
  • MetaMask Only: To create production builds, you need to install Google Play Licensing Library via the SDK Manager in Android Studio.
• Install the Android NDK (version 21.4.7075529), via Android Studio's SDK Manager.
  • Go to Settings > Appearance & Behavior > System Settings > Android SDK
    • Shortcut: Selecting More Actions > SDK Manager from the "Welcome to Android Studio" page will also bring you here.
  • Select SDK Tools tab
  • Check Show Package Details option below the tools list to show available versions
  • Locate NDK (Side-by-side) option in the tools list
  • Check NDK version 21.4.7075529
  • Locate CMake option in the tools list
  • Check CMake version 3.22.1
  • Click "Apply" or "OK" to download
• Linux only:
  • Ensure that you have the secret-tool binary on your machine.
    • Part of the libsecret-tools package on Debian/Ubuntu based distributions.
• Install the correct emulator
  • Follow the instructions at:
    • React Native Getting Started - Android (React Native CLI Quickstart -> [your OS] -> Android)
    • FYI: as of today (7/18/23) there is currently an issue when running detox on android 12 and 13 (API 32/33) which prevents the tests from running. The issue is, the tap() action is treated like a tapAndHold() action. See the open issue in wix/detox here
    • More details can be found on the Android Developer site
  • You should use the following:
    • Android OS Version: Latest, unless told otherwise
    • Device: Google Pixel 5
• Finally, start the emulator from Android Studio:
  • Open "Virtual Device Manager"
  • Launch emulator for "Pixel 5 <relevant API version mentioned in React Native Getting Started>"

iOS

• Install the iOS dependencies
  • React Native Getting Started - iOS (React Native CLI Quickstart -> [your OS] -> iOS)
• Install the correct simulator
  • iOS OS Version: Latest, unless told otherwise
  • Device: iPhone 12 Pro

Building Locally

• Clone this repo:

git clone ...
cd metamask-mobile

• MetaMask Only: Rename the .*.env.example files (remove the .example) in the root of the project and fill in the appropriate values for each key. Get the values from another MetaMask Mobile developer.
• Non-MetaMask Only: In the project root folder run
• If you intend to use WalletConnect v2 during your development, you should register to get a projectId from WalletConnect website and set the WALLET_CONNECT_PROJECT_ID value accordingly in .js.env file.

  cp .ios.env.example .ios.env && \
  cp .android.env.example .android.env && \
  cp .js.env.example .js.env

• Non-MetaMask Only: Create an account and generate your own API key at Infura in order to connect to main and test nets. Fill MM_INFURA_PROJECT_ID in .js.env. (App will run without it, but will not be able to connect to actual network.)

• Non-MetaMask Only: Fill MM_SENTRY_DSN in .js.env if you want the app to emit logs to your own Sentry project.

• Install the app:

yarn setup # not the usual install command, this will run a lengthy postinstall flow

• Then, in one terminal, run:

yarn watch

Android

yarn start:android

iOS

yarn start:ios

Build Troubleshooting

Unfortunately, the build system may fail to pick up local changes, such as installing new NPM packages or yarn linking a dependency. If the app is behaving strangely or not picking up your local changes, it may be due to build issues. To ensure that you're starting with a clean slate, close all emulators/simulators, stop the yarn watch process, and run:

yarn clean

# if you're going to `yarn link` any packages,
# do that here, before the next command

yarn watch:clean

# ...and then, in another terminal

yarn start:ios

# or

yarn start:android

If yarn link fails after going through these steps, try directly yarn adding the local files instead.

Debugging

First, make sure you have the following running:

• yarn watch
• Your Android emulator or iOS simulator
• yarn start:android or yarn start:ios

Next, install the Flipper desktop app (verified working with v0.127.0)

• Once Flipper is installed, configure your system as follows:
  • Install react-devtools: npm i -g [email protected]
  • Update Android SDK location settings by accessing Flipper's settings via the Gear Icon -> Settings
    • Example SDK path: /Users/<USER_NAME>/Library/Android/sdk

Finally, check that the debugger is working:

• Open your emulator or simulator alongside the Flipper app
• Flipper should auto-detect the device and the application to debug
• You should now be able to access features such as Logs

Debugging Physical iOS devices

• Debugging physical iOS devices requires idb to be installed, which consists of 2 parts
• Install the two idb parts:
  1. brew tap facebook/fb & brew install idb-companion
  2. pip3.9 install fb-idb (This step may require that you install python3 via python -m pip3 install --upgrade pip)

Debug a website inside the WebView (in-app browser)

Android

• Run the app in debug mode (for example, in a simulator)
• Open Chrome on your desktop
• Go to chrome://inspect/#devices
• Look for the device and click inspect

iOS

• Run the app in debug mode (for example, in a simulator)
• Open Safari on your desktop
• Go to the menu Develop -> [Your device] -> [Website]

You should see the console for the website that is running inside the WebView

Miscellaneous

• Troubleshooting for React Native
• Flipper Documentation

Running Tests

Unit Tests

yarn test:unit

E2E Tests

Platforms

For both iOS and Android platforms, our chosen E2E test framework is Detox. We also utilize Appium for Android (wdio folder).

Test wallet

E2E tests use a wallet able to access testnet and mainnet. On Bitrise CI, the wallet is created using the secret recovery phrase from secret env var. For local testing, the wallet is created using the secret recovery phrase from the .e2e.env file.

Detox

All tests live within the e2e/specs folder.

iOS

Prerequisites for running tests:

• Make sure to install detox-cli by referring to the instructions mentioned here.
• Additionally, install applesimutils by following the guidelines provided here.
• Before running any tests, it's recommended to refer to the iOS section above and check the latest simulator device specified under Install the correct simulator.
• The default device for iOS is the iPhone 12 Pro and Android the Pixel 5. Ensure you have these set up.
• Make sure that Metro is running. Use this command to launch the metro server:

yarn watch

You can trigger the tests against a release or debug build. It recommended that you trigger the tests against a debug build.

To trigger the tests on a debug build run this command:

For iOS

yarn test:e2e:ios:debug

and on Android:

yarn test:e2e:android:debug

If you choose to run tests against a release build, you can do so by running this command:

For iOS

yarn test:e2e:ios

and on Android:

yarn test:e2e:android

If you have already built the application for Detox and want to run a specific test from the test folder, you can use this command:

For iOS

yarn test:e2e:ios:debug:single e2e/specs/TEST_NAME.spec.js

and on Android:

yarn test:e2e:android:debug:single e2e/specs/TEST_NAME.spec.js

To run tests associated with a certain tag, you can do so using the --testNamePattern flag. For example:

yarn test:e2e:ios:debug --testNamePattern="Smoke"

yarn test:e2e:android:debug --testNamePattern="Smoke"

This runs all tests that are tagged "Smoke"

Appium

The appium tests lives within the wdio/feature folder.

By default the tests use an avd named Android 11 - Pixel 4a API 31, with API Level 30 (Android 11). You can modify the emulator and platform version by navigating to wdio/config/android.config.debug.js and adjusting the values of deviceName to match your emulator's name, and platformVersion to match your operating system's version. Make sure to verify that the config file accurately represents your emulator settings before executing any tests.

The sequence in which you should run tests:

create a test build using this command:

yarn start:android:qa

Then run tests using this command:

yarn test:wdio:android

If you want to run a specific test, you can include the --spec flag in the aforementioned command. For example:

yarn test:wdio:android --spec ./wdio/features/Onboarding/CreateNewWallet.feature

Changing dependencies

Whenever you change dependencies (adding, removing, or updating, either in package.json or yarn.lock), there are various files that must be kept up-to-date.

• yarn.lock:
  • Run yarn setup again after your changes to ensure yarn.lock has been properly updated.
• The allow-scripts configuration in package.json
  • Run yarn allow-scripts auto to update the allow-scripts configuration automatically. This config determines whether the package's install/postinstall scripts are allowed to run. Review each new package to determine whether the install script needs to run or not, testing if necessary.
  • Unfortunately, yarn allow-scripts auto will behave inconsistently on different platforms. macOS and Windows users may see extraneous changes relating to optional dependencies.

Architecture

To get a better understanding of the internal architecture of this app take a look at this diagram.

Storybook

We have begun documenting our components using Storybook. Please read the Documentation Guidelines to get up and running.

Other Docs

• Adding Confirmations