Developing Ethereum Dapps with Truffle and MetaMask

Feb 4, 2017 Update: A new version of Truffle has been released, Version 3, and is not yet reflected in this tutorial! To get the latest word on that migration process, check out the Truffle 3 migration guide. We will eventually update this tutorial for Truffle 3, but until then, if you just want to get your feet wet, maybe try this tutorial out with Truffle 2.0. npm install -g truffle@2. You might also find Truffle 3 to be easy to start with Webpack using this video tutorial.

If you’re interested in building web apps with the Ethereum blockchain, you may have found the Truffle web framework to be a nice fit for your needs.

For many types of Dapps (Distributed Apps), Truffle does everything you could want: It compiles your blockchain contracts, injects them into your web app, and can even run a test suite against them!

This is all great for you, but what about your users? Truffle has some great defaults for users who are willing to run a local Ethereum JSON RPC server on their computer, but what about your users who just want to sign on and get started?

With Metamask, all your users need to do is install our Chrome plugin, and they will have their own secure blockchain accounts right there in the convenience of their browsers.

Metamask is just a Developer Preview right now, and has not been released to the general public. We don’t recommend putting serious funds in it, but instead encourage you to use it to help prepare your dapps for Ethereum browsers.

It’s possible your Truffle Dapp is already compatible with Metamask, but if you’re like me, you want to go through your project and see what it’s like from your user’s perspective.

Just in case you haven’t used Truffle before, I’m going to start by describing how to scaffold a minimal Truffle dapp. If you already have one set up, feel free to jump ahead to Setting up Metamask.

Installing Truffle Dependencies

You’re going to need to have installed node.js.

From there, you need to install truffle (npm install -g truffle).

Also, you’re going to need to run a local blockchain RPC server to test and develop against. I recommend using testrpc, which you install by running npm install -g ethereumjs-testrpc.

Next let’s make sure we have our testrpc running in the background. Open your terminal and run the command testrpc. That's all! It runs on port 8545by default, just like most Ethereum RPCs, and so does Truffle.

Also note that when testrpc first starts, it prints out a list of accounts that will be pre-funded with ether, along with a twelve-word seed phrase for re-generating those accounts. You can use this seed phrase to initialize your MetaMask client with the same accounts, and you’ll have lots of Ether when you start! (Ether is used to pay for network usage, or gas, on the Ethereum network)

If you wanted to start up testrpc with the accounts you already have in MetaMask, you can tell testrpc what seed phrase to use with the -m flag. For example:

$ testrpc -m "concert load couple harbor equip island argue ramp clarify fence smart topic"

Setting up a simple Truffle Dapp

Next, let’s generate a basic Truffle dapp. The default result of truffle initis a simple example currency.

To get it up and running, run these commands:

mkdir my-money # Create a folder for your new dapp
cd my-money # Move into that folder
truffle init # Initialize a default truffle project in that folder
truffle migrate # Build, compile, & deploy the dapp
truffle serve # Host your web interface on port 8080

We just deployed a simple alt-coin called MetaCoin to our local blockchain, and it's available to our browser on http://localhost:8080!

If you visit it, you’ll see that by default this new Dapp template signs you in with the first account on your testrpc account list, which happens to be the same account that got pre-populated with 10k shiny new Metacoins! That's because when you ran truffle migrate, Truffle used your first account as the contract publisher, and the contract says to fund the creator's account with 10k coins.

You can now send those coins to any account you want, for example, the second account in your testrpc list! If you enter an address and a value, and hit send, you'll see your balance go down!

If that seems a little too easy, I’d agree with you! That’s why Metamask gives the user an opportunity to approve every transaction that a Dapp attempts, and that’s more secure!

Let’s try connecting to the same account through Metamask, and see how easy it is!

Setting up Metamask

Now you’ll want to install Metamask from the Chrome store.

When you first open Metamask, it will let you either create a new wallet or restore from a seed. Since both Metamask and testrpc use the bip44 standard for wallet generation, you can Restore Existing Vault, and enter the mnemonic that testrpc output when you first started it. It should be 12 words long.

You’ll also need to provide a password, which is used to encrypt your wallet.

By default you get three accounts, and they’ll be the same as the first three accounts in your testrpc list.

To use Metamask with your testrpc accounts, you need to point it at yourtestrpc address as its RPC provider, which by default is localhost:8545. MetaMask provides a menu item for quickly switching to this local port.

  1. Open Metamask
  2. Click the current network name in the top right.
  3. Select your current testrpc address, which is probbly Localhost 8545.

Metamask will close at this point to restart itself.

You can now sign into your Dapp with Metamask.

  1. Open Metamask
  2. Enter your password
  3. Reload the Dapp page (some dapps will notice when you change accounts, but this basic one doesn’t)

You should now see your first account’s MetaCoin balance! If you switch accounts, you should see theirs (none, unless you’ve sent to one!).

To send some Metacoin to one of your Metamask accounts, you’re going to need that account’s address.

To copy a Metamask account’s address:

  1. Open Metamask
  2. Click the details arrow next to the account whose address you want.
  3. Click the “Copy Address” button.

You now you have a copy of your address to send to!

Sending Metacoin from Metamask: So Meta!

If you connect to your first account, you should see you have some MetaCoin, and if we look in our Metamask plugin, we should have some ether too!

It’s important that we have ether, because it’s not only a currency for trade, it’s also the currency for processing transactions on the Ethereum blockchain. This processing fee is referred to as “gas”.

Let’s try sending some Metacoin from one of our Metamask accounts to another.

Select the account that has the Metacoin and Ether, so that the Dapp shows a MetaCoin balance.

Now we want to copy the address of another account you control to send to. In MetaMask, click the Switch Accounts icon in the top right.

If you only have one account, click the + at the bottom of this screen to add a new account.

When you see another account in the list, click the Copy Address button on it, and then you can paste that into the Dapp’s To field, along with how much MetaCoin you'd like to send, and hit Send!

You should see a notification pop-up, notifying you that you have a transaction to approve.

You can now Approve or Reject the transaction, or close the notification, and review the transaction in MetaMask later.

This is one way that Metamask is a safer Ethereum browsing experience than running your own RPC. While a pre-authenticated RPC automatically approves all requests sent to it, Metamask gives the user an opportunity to review and approve or reject each transaction that’s requested by the dapp. Long term, making transactions easy to intelligently review is an important priority for MetaMask.

Wrapping Up

This has been a simple example, but hopefully shows how Truffle and Metamask work together. They are able to pretty much work out of the box! That’s because Truffle helps you write web3-compliant dapps. Web3 is a Javascript API declared by the core Ethereum team, and Metamask injects it directly into the Dapp’s context!

This makes connecting to a Truffle Dapp with Metamask as easy as connecting with your own RPC, but it’s a lot easier for your users.

That’s because Metamask is a hyper-light client that doesn’t replicate the entire blockchain locally, but it does let users manage their own accounts, so they can casually benefit from the security of private key management, while placing trust for block validation on Metamask’s configured RPC provider.

We hope this has been a useful introduction to developing with Truffle and Metamask!

Please, leave a comment or question, start a discussion on github, or Tweet at us on Twitter. We’re trying to make Metamask the easiest tool to let anyone benefit from using Distributed Apps on the Ethereum Blockchain.