Skip to content

Using Truffle to Deploy to Moonbeam


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 v0.18.1 tag which is based on the v0.18.1 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.

Creating a Project using the Moonbeam Truffle Box

To get started with the Moonbeam Truffle box, if you have Truffle installed globally, you can execute:

mkdir moonbeam-truffle-box && cd moonbeam-truffle-box
truffle unbox PureStake/moonbeam-truffle-box

Unbox Moonbeam Truffle box

Nevertheless, the box also has Truffle as a dependency in case you do not want to have it installed globally. In such a case, you can directly clone the following repository:

git clone
cd moonbeam-truffle-box

With the files in your local system, the next step is to install all dependencies by running:

npm install


We noticed an error while installing the packages with npm version 7.0.15. You can downgrade npm by running npm install -g npm@version and setting the version to the one desired. For example, 7.0.8 or 6.14.9.

The Truffle Configuration File

Navigate inside the directory to take a look at the truffle-config.js file (for the purpose 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, '')
         network_id: 1281,  // 0x501 in hex,
   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.

For deployments to Moonbeam-based networks, you need to provide the private key of an address that holds funds. If you decide to use a development node, it will come with 10 pre-funded accounts that you can use. Otherwise, you can create an account in MetaMask and fund it. For Moonbase Alpha, you can get tokens from the faucet. Once you have an acouunt with funds, you will need to export its private key.

Below you can find network configurations for all of our networks:

moonbeam: {
  provider: () => {
     return new HDWalletProvider(privateKeyMoonbeam, '') // Insert your private key here
  network_id: 1284 (hex: 0x504),
moonriver: {
  provider: () => {
     return new HDWalletProvider(privateKeyMoonriver, '') // Insert your private key here
  network_id: 1285 (hex: 0x505),
moonbase: {
  provider: () => {
     return new HDWalletProvider(privateKeyMoonbase, '') // Insert your private key here
  network_id: 1287 (hex: 0x507),
dev: {
  provider: () => {
     return new HDWalletProvider(privateKeyDev, '') // Insert your private key here
  network_id: 1281 (hex: 0x501),

Using the Moonbeam Truffle Plugin to Run a 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

You also have the option to pause and unpause your Moonbeam development node:

truffle run moonbeam pause
truffle run moonbeam unpause

You can see the output of these commands in the following image:

Install Moonbeam Truffle box


If you are familiar with Docker, you can skip the plugin commands and interact with the Docker image directly.

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 moonbeam
truffle migrate --network moonriver
truffle migrate --network moonbase
truffle migrate --network dev

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

Successful contract deployment actions