Skip to content

Interacting with Moonbeam Using Truffle

You can find all of the relevant code for this tutorial on the code snippets page


This guide walks through the process of deploying a Solidity-based smart contract to a Moonbeam node using Truffle, a commonly used development tool for smart contracts on Ethereum. Given Moonbeam’s Ethereum compatibility features, Truffle can be used directly with a Moonbeam node.


This tutorial was created using the tutorial-v7 tag which is based on the v0.7.0 release of Moonbase Alpha. The Moonbeam platform and the Frontier components it relies on for Substrate-based Ethereum compatibility are still under very active development. The examples in this guide assumes you have a MacOS or Ubuntu 18.04-based environment and will need to be adapted accordingly for Windows.

For this guide, you will need to have a Moonbeam development node running in --dev mode. This can be done by either following the steps detailed here or by using the Moonbeam Truffle plugin, which we'll use in this tutorial's examples.

Checking Prerequisites

We need to install Node.js (we'll use v15.x) and the npm package manager. You can download directly from Node.js or in your terminal:

curl -sL | sudo -E bash -

sudo apt install -y nodejs
# You can use homebrew (
brew install node

# Or you can use nvm (
nvm install node

We can verify that everything is installed correctly by querying the version for each package:

node -v
npm -v

In addition, you can globally install Truffle by running:

npm install -g truffle

As of this guide's publish date, the versions used were 15.12.0, 7.6.3, and 5.2.4 respectively.


For the following examples, you don't need to have Truffle globally installed, as it is included as a dependency on the Moonbeam Truffle box. If you prefer, you can run npx truffle or ./node_modules/.bin/truffle instead of truffle.

Getting Started with Truffle

To ease the process of getting started with Truffle, we have released the Moonbeam Truffle box. This provides a boilerplate setup to speed up the rampup process to deploy contracts on Moonbeam. To read more about the box, you can visit this link.

To download the Moonbeam Truffle box, follow these instructions. Once inside the directoy, let's take a look at the truffle-config.js file (for the purpuse of this guide, some information was removed):

const HDWalletProvider = require('@truffle/hdwallet-provider');
// Moonbeam Development Node Private Key
const privateKeyDev =
module.exports = {
   networks: {
      dev: {
         provider: () => {
            return new HDWalletProvider(privateKeyDev, 'http://localhost:9933/')
         network_id: 1281,
   plugins: ['moonbeam-truffle-plugin']

Note that we are using HD-Wallet-Provider from Truffle as the Hierarchical Deterministic wallet. Also, we've defined a dev network that points to the development node provider URL, and the private key of the development account, which holds all funds in the development node, is included.

Running a Development Node

To set up a Moonbeam development node, you can follow this tutorial. The process takes around 40 minutes in total, and you need to install Substrate and all its dependencies. The Moonbeam Truffle plugin provides a way to get started with a development node much quicker, and the only requirement is to have Docker installed (at time of writing the Docker version used was 19.03.6).

To start a Moonbeam development node in your local environment, we need to first download the corresponding Docker image:

truffle run moonbeam install

Docker image download

Once downloaded, we can proceed to start the local node with the following command:

truffle run moonbeam start

You will see a message indicating that the node has started, followed by both of the endpoinds available.

Moonbeam local node started

Once you are finished using your Moonbeam development node, you can run the following lines to stop it and remove the Docker image if that is the case:

truffle run moonbeam stop && \
truffle run moonbeam remove

Moonbeam local node stoped and image removed

The Contract File

There is also a ERC-20 token contract included with the Truffle box:

pragma solidity ^0.7.5;

// Import OpenZeppelin Contract
import "@openzeppelin/contracts/token/ERC20/ERC20.sol";

// This ERC-20 contract mints the specified amount of tokens to the contract creator.
contract MyToken is ERC20 {
    constructor(uint256 initialSupply) ERC20("MyToken", "MYTOK")
        _mint(msg.sender, initialSupply);

This is a simple ERC-20 contract based on the OpenZepplin ERC-20 contract. It creates "MyToken" with "MYTOK" symbol and the standard 18 decimal places. Furthermore, it assigns the created initial token supply to the contract creator.

If we take a look at the Truffle contract migration script under migrations/2_deploy_contracts.js, it contains the following:

var MyToken = artifacts.require('MyToken');

module.exports = function (deployer) {
   deployer.deploy(MyToken, '8000000000000000000000000');

"8000000000000000000000000" is the number of tokens to initially mint with the contract, i.e., 8 million with 18 decimal places.

Deploying a Contract to Moonbeam Using Truffle

Before we can deploy our contracts, we must compile them. (We say "contracts" because normal Truffle deployments include the Migrations.sol contract.) You can do this with the following command:

truffle compile

If successful, you should see output like the following:

Truffle compile success message

Now we are ready to deploy the compiled contracts. You can do this with the following command:

truffle migrate --network dev

If successful, you will see deployment actions, including the address of the deployed contract:

Successful contract deployment actions

Once you have followed the MetaMask guide and Remix guide, you will be able to take the deployed contract address that is returned and load it into MetaMask or Remix.

We Want to Hear From You

This is a simple example, but it provides context for how you can start working with Moonbeam and trying out its Ethereum compatibility features. We are interested in hearing about your experience following the steps in this guide or trying other Ethereum-based tools with Moonbeam. Feel free to join us in the Moonbeam Discord here. We would love to hear your feedback on Moonbeam and answer any questions that you have.