metamask / metamask-mobile

Mobile web browser providing access to websites that use the Ethereum blockchain

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.

Documentation

• Architecture
• Development Environment Setup
• Build Troubleshooting
• Testing
• Debugging
• Storybook
• Miscellaneous

Getting started

Environment setup

Before running the app, make sure your development environment has all the required tools. Several of these tools (ie Node and Ruby) may require specific versions in order to successfully build the app.

Setup your development environment

Building the app

Clone the project

git clone [email protected]:MetaMask/metamask-mobile.git && \
cd metamask-mobile

Install dependencies

yarn setup

Not the usual install command, this will run scripts and a lengthy postinstall flow

Running the app

Run Metro bundler

yarn watch

Like a local server for the app

Run on a iOS device

yarn start:ios

Run on an Android device

yarn start:android

metamask-mobile's Issues

Accounts & Settings

Questions
Settings:

1. In invision, can the top-right settings (etherscan, view address) get folded in to the accounts menu, and let the accounts "settings" (view seed, switch currency) live in the top-right? Basically: swap.
2. Is a "download state logs" possible? What else would we include for help debugging? Open console?
3. Custom RPCs part of MVP? Do we need any other features that will make it easy to develop dapps for a mobile browser? Let's stay the browser devs <3
4. What type of deep linking (if any) do we need to handle?

Accounts:

1. Hardware part of MVP? Trezor works on Android
2. Import part of MVP? Prolly requires putting the key in plaintext which ain't great
3. Need UI for account removal
4. Can we make the "import" or other "add" options more obvious than a + ?
5. What balance do we show under each account? ETH only? Tokens/collectibles too?

Integrate CodePush

This will allow us to release updates over the air (without having to re-submit a new build to the App Store / Play Store)

https://github.com/Microsoft/react-native-code-push

Lock app and require authentication while coming from background

We can use this library: https://github.com/naoufal/react-native-touch-id

MVP feature set

This is a living doc, you are welcome to edit without permission.
Numbers correspond to the open questions in each section.

Onboarding

• Create account flow
  • Terms
  • Create password
  • Seed Warning 1
  • Seed Display
  • Seed Confirm
  • Setup FaceID / Device PIN
  • Welcome 2
• Import account flow
  • Terms
  • Seed Confirm
  • Setup FaceID / Device PIN
  • Welcome 2

Questions

1. What can we do to make the seed experience good?
2. Do we want a welcome / splash / tutorial after onboarding is complete?
3. Should terms come later? What's best thing to begin onboarding with?
4. Can we re-use terms from the extension? (Check with Legal)

Navigation

• Bottom Nav 1
  • Dapps
  • Wallet
  • Transfer
• Top Nav 2
  • Left: Accounts
  • Right: Settings 3

Questions

1. Names for bottom three nav items? (Dapps, Explore, Web / Transfer, Send, etc)
2. What about moving Accounts to the right? Mirrors extension, common design pattern
3. Could account "Settings" (Etherscan, copy address) live in Accounts?

Dapps page

• Browser functionality
  • Basics: back, forward, stop, reload
  • Historical URL bar
• Two tabs 1
  • Explore (show icons / tiles of popular dapps) 2
  • Favorites (bookmarks) 3
• Interacting with dapps
  • Confirm screen 4
  • Login / Connect screen 5

Questions

1. Information hierarchy: URL bar at top, above "Explore" / "Favorites" tabs?
2. How do we populate the explore page? Custom? Use State of the Dapps?
3. Do we want browser extras, like bookmarks / favorites, history, QR scanning for URLs?
4. What does the confirm screen (for signing tx or signing data) look like (when prompted by a dapp)?
5. Are we supporting 1102 by default? Yes
6. What does the "connect" or "login" UI look like?

Wallet page

• Name, balance 5
• Transfer button 1
  • Deposit screen 4
• Tabs
  • Tokens 2
  • Transactions 3
  • Collectibles

Questions

1. Maybe Send/Deposit buttons (as in the extension) makes sense - no idea what onboarding / first ETH numbers are like, but probably good to spoon-feed here.
2. Does MVP have automatic token detection?
3. Not in invision but we should include
4. Should tapping a transaction just go to Etherscan? Could build tx detail view after MVP
5. What is the deposit experience? Coinbase, shapeshift, possibly Simplex or Coinmama?
6. Where is my address?
7. Do we want balance showing on the main page? Perhaps want to add a setting to hide the user's balance by default?

Transfer page

• Send
  • From
  • To 1
  • Token 2
  • Amount
  • Transaction Fee 3
• Receive 6

Questions

1. Should QR scanner part of MVP?
2. As with the extension designs, think we need a better label
3. "Advanced" leads to the current production options?
4. How does this screen look with the keyboard / number pad popped up?
5. Did we consider a one-by-one screen? This is the way most other dapp browsers have implemented, and there's some evidence that sequential forms do much better on mobile.
6. Consider making the QR foxy/cute? Would be fun to share these.
7. Should "Receive" also a link to the Coinbase / Deposit flow?

Security

• FaceID / PIN when app is foregrounded
• Blank screen when switching between apps

Questions

1. How are we handling the user's key? Secure enclave?

Accounts

• Create from same seed
• Import 1
• Hardware 1

Questions

1. Hardware part of MVP? Trezor works on Android
2. Import part of MVP? Prolly requires putting the key in plaintext which ain't great
3. Account removal?
4. Animation - tray vs. slide over? Tray makes logical sense, familiar from Google, etc.
5. Can we make the "import" or other "add" options more obvious than a + ?
6. What balance do we show under each account? ETH only? Tokens/collectibles too?

Settings / Other

• Settings 1: Top Right 1
• Settings 2: In Accounts tray 1
  • Network toggle 2
  • Currency conversion
  • New RPC URL 3
  • State Logs 4
  • Reveal Seed

Questions

1. In invision, can the top-right settings (etherscan, view address) get folded in to the accounts menu, and let the accounts "settings" (view seed, switch currency) live in the top-right? Basically: swap.
2. ~Do we support testnets? ~ Yes.
3. Part of MVP?
4. Is a "download state logs" possible? What else would we include for help debugging? Open console?
5. Do we need any other features that will make it easy to develop dapps for a mobile browser? Let's stay the browser devs <3
6. What type of deep linking (if any) do we need to handle?

Differentiation

• Mobile signing for desktop dapps
• Generate payment URLs on extension, submit from the phone
• Gnosis SAFE support
• By default, could use the same seed on desktop & mobile
  • do we need a feature to mitigate nonce issues?
• save encrypted version of seed phrase in phone keychain?
• save encrypted version of seed phrase in desktop extension?

Set global currency

and make sure all the conversions are using it.

Once it's done make sure we're doing it everywhere by making a project wide search for USD and $

QR Scanner

Import Seed screen

Account settings

Login / Unlock screen

Tokens view

Dapp showcase landing page

• could use something from state of the dapps?
• would be awesome to have a shiny full-width experience

Investigate GABA module format

If GABA isn't compiled to CommonJS, the Metro bundler blows up. We should look into this, as GABA should ideally be imported into this project as ES. This is a Metro-specific issue.

Transaction approval screen

Encrypt keychain data

react-native-keychain already uses the android keystore system which is good enough but apple's keychain has been hacked in the pass so we shouldn't store plain text.

One potenital solution is to use the encryptor (which uses AES internally) and generate a key based on the device id

Change inpage/inpage.js -> entry/entry.js

We should change the name of the inpage script from npage/inpage.js to entry/entry.js.

Send screen

• Should QR scanner be part of MVP?
• As with the extension designs, think we need a better label for the
• "Advanced" leads to the current production options (number inputs for price and limit)?
• How does this screen look with the keyboard / number pad popped up?

Navigation

Navigation

• Bottom Nav 1
  • Dapps
  • Wallet
  • Transfer
• Top Nav 2
  • Left: Accounts
  • Right: Settings 3

Questions

1. Names for bottom three nav items? (Dapps, Explore, Web / Transfer, Send, etc)
2. What about moving Accounts to the right? Mirrors extension, common design pattern
3. Could account "Settings" (Etherscan, copy address) live in Accounts?

Main browser functionality

• Load pages
• Forward / back
• URL autocomplete?
• Favorites / bookmarks?

Transfer Flow

Questions

1. Should QR scanner be part of MVP?
2. "Advanced" leads to the current production options?
3. How does this screen look with the keyboard / number pad popped up?
4. Did we consider a one-by-one screen? This is the way most other dapp browsers have implemented, and there's some evidence that sequential forms do better on mobile.
5. Consider making the QR foxy/cute? Would be fun to share these.
6. Should "Receive" also a link to the Coinbase / Deposit flow?

Implement loading spinner during page loads

Since we switched from WebView to WKWebView, we lost the built-in loading spinner between page loads. We should re-enable one, or if that's not possible, replace the "refresh" icon with a loading spinner during page loads.

Setup Fabric / Crashlytics

This is the equivalent of sentry. Helpful to find / debug issues once we start releasing betas

Engine needs to accept initial state in the constructor

This is required to be able to persist data between sessions

The extension is doing exactly that right here:https://github.com/MetaMask/metamask-extension/blob/develop/app/scripts/background.js#L257

Explore / Browse Flow

Questions

1. Information hierarchy: URL bar at top, above "Explore" / "Favorites" tabs?
2. How do we populate the explore page? Custom? Use State of the Dapps?
3. Do we want browser extras, like bookmarks / favorites, history, QR scanning for URLs?
4. What does the confirm screen (for signing tx or signing data) look like (when prompted by a dapp)?
5. What does the "connect" or "login" UI look like?

Receive screen

Account list

Injection approval screen

relates to MetaMask/Design#36

Competitive analysis: Onboarding

Account creation & import

Improve Android injection logic

Android WebViews are safely polyfilled during startup, but they rely on a timeout to avoid being overwritten by the bridge once it loads. We need to be able to polyfill and let users call postMessage immediately, not after an arbitrary timeout. We should look to monkey-patch the underlying native code like we do for iOS.

Setup fastlane

We will need it to generate appstore / playstore builds and release betas

Externalize blockies.js

We should externalize blockies.js somehow.

Collectibles view

Fix Browser code coverage

The Browser component executes an asynchronous filesystem read in its componentDidMount method. This operation (or any other asynchronous operation) breaks the Istanbul code coverage produced by Jest and can't be ignored using any flavor of ignore syntax. If this single statement is commented out manually, 100% code coverage is achieved, hinting at a transpilation error.

Ideally, we should find a way to ignore this line or work around this issue to achieve 100% coverage.

Asset transaction history

Use Keychain for private key storage

We might want to use this: https://github.com/oblador/react-native-keychain

Improve CI workflow

We need to be generating appstore / playstore builds on every PR so we don't get surprises at the time of releasing.

LOTS of things breaks while building in release mode and we want to know as early as possible

Account overview screen

Detect Jailbroken / Rooted devices

We should warn users of the security risks of storing private keys with a jailbroken / rooted device

Persist redux state

• Figure out what's the mimium amount of data that we have to persist (check the contents of the state engine and decide)
• Write data when going to background
• Write data every X seconds (ideally via bg thread)
• Restore while going to foreground

Consider using https://blog.reactnativecoach.com/the-definitive-guide-to-redux-persist-84738167975

Scan QR code

In a mobile wallet this is a must.
We should use: https://github.com/react-native-community/react-native-camera

Onboarding Flow

Onboarding

• Create account flow
  • Terms
  • Create password
  • Seed Warning 2
  • Seed Display
  • Seed Confirm
  • Setup FaceID / Device PIN
  • Welcome 3
• Import account flow
  • Terms
  • Seed Confirm
  • Setup FaceID / Device PIN
  • Welcome

Open Questions

1. What's the order?
2. Should we force the user to do seed phrase on setup?
3. What can we do to make the seed experience good? Anything with extension?
4. Do we want a welcome / splash / tutorial after onboarding is complete?
5. Can we re-use terms from the extension? (Check with Legal)
6. Do we want to encourage / discourage using the same seed as extension? (Nonce tracking is hard)

Message approval screen

Wallet Flow

• Name, balance 5
• Transfer button 1
  • Deposit screen 4
• Tabs
  • Tokens 2
  • Transactions 3
  • Collectibles

Questions

1. Maybe Send/Deposit buttons (as in the extension) makes sense - no idea what onboarding / first ETH numbers are like, but probably good to spoon-feed here.
2. Does MVP have automatic token detection?
3. One single transaction list vs. per-asset transaction lists?
4. Should tapping a transaction just go to Etherscan? Could build tx detail view after MVP
5. What is the deposit experience? Coinbase, shapeshift, possibly Simplex or Coinmama?
6. Where is my address?
7. Do we want balance showing on the main page? Perhaps want to add a setting to hide the user's balance by default?

Intercept HTTP requests in CustomWebview and add Polyfill (android)

This will make the android injection, since it would be a fallback in case the polyfill via onProgressChange fails (haven't seen it failing anymore tho)

Asset balance

Browserified entry files are broken on Android Webview

08-02 01:49:35.398 26490-26490/com.metamask D/CustomWebview: Uncaught SyntaxError: Unexpected end of input

App info screen

Fix aes-js

The build output of the version of aes-js we use produces invalid JavaScript that breaks the Metro bundler. For now, we're monkey-patching this as part of our postinstall script, but we should probably update the dependency to make this nicer.

Create Password screen

App settings