Skip to content

Setting Up a Moonbeam Node and Connecting to the Polkadot JS GUI

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

Introduction

This guide outlines the steps needed to create a development node for testing the Ethereum compatibility features of Moonbeam.

Note

This tutorial was created using the tutorial-v7 tag 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.

A Moonbeam development node is your own personal development environment for building and testing applications on Moonbeam. For Ethereum developers, it is comparable to Ganache. It enables you to get started quickly and easily without the overhead of a relay chain. You can spin up your node with the --sealing option to author blocks instantly, manually, or at a custom interval after transactions are received. By default a block will be created when a transaction is received, which is similar to Ganache's instamine feature.

If you follow to the end of this guide, you will have a Moonbeam development node running in your local environment, with 10 pre-funded accounts, and will be able to connect it to the default Polkadot JS GUI.

There are two ways to get started running a Moonbeam node: you can use Docker to run a pre-built binary or you can compile the binary locally and set up a development node yourself. Using Docker is a quick and convenient way to get started as you won't have to install Substrate and all the dependencies, and you can skip the building the node process as well. It does require you to install Docker. On the other hand, if you decide you want to go through the process of building your own development node, it could take roughly 30 minutes or longer to complete depending on your hardware.

Getting Started with Docker

Using Docker enables you to spin up a node in a matter of seconds. Once you have Docker installed, then you can execute the following command to download the corresponding image:

docker pull purestake/moonbeam:tutorial-v7

The tail end of the console log should look like this:

Docker - imaged pulled

Once the Docker image is downloaded, the next step is to run the image.

You can run the Docker image using the following:

docker run --rm --name moonbeam_development --network host \
purestake/moonbeam:tutorial-v7 \
--dev
docker run --rm --name moonbeam_development -p 9944:9944 -p 9933:9933 \
purestake/moonbeam:tutorial-v7 \
--dev --ws-external --rpc-external
docker run --rm --name moonbeam_development -p 9944:9944 -p 9933:9933 ^
purestake/moonbeam:tutorial-v7 ^
--dev --ws-external --rpc-external

This should spin up a Moonbeam development node in instant seal mode for local testing, so that blocks are authored instantly as transactions are received. If successful, you should see an output showing an idle state waiting for blocks to be authored:

Docker - output shows blocks being produced

For more information on some of the flags and options used in the example, check out Common Flags and Options. If you want to see a complete list of all of the flags, options, and subcommands, open the help menu by running:

docker run --rm --name moonbeam_development \
purestake/moonbeam \
--help

To continue on with the tutorial, the next section is not necessary as you've already spun up a node with Docker. You can skip ahead to Connecting Polkadot JS Apps to a Local Moonbeam Node.

Getting Started with the Binary File

Note

If you know what you are doing, you can directly download the precompiled binaries attached to each release on the Moonbeam-release page. These will not work in all systems. For example, the binaries only work with x86-64 Linux with specific versions of dependencies. The safest way to ensure compatibility is to compile the binary in the system where it will be run from.

First, start by cloning a specific tag of the Moonbeam repo that you can find here:

https://github.com/PureStake/moonbeam/

git clone -b tutorial-v7 https://github.com/PureStake/moonbeam
cd moonbeam

Next, install Substrate and all its prerequisites (including Rust) by executing:

curl https://getsubstrate.io -sSf | bash -s -- --fast

Once you have followed all of the procedures above, it's time to build the development node by running:

cargo build --release

If a cargo not found error shows up in the terminal, manually add Rust to your system path (or restart your system):

source $HOME/.cargo/env

Note

The initial build will take a while. Depending on your hardware, you should expect approximately 30 minutes for the build process to finish.

Here is what the tail end of the build output should look like:

End of build output

Then, you will want to run the node in dev mode using the following command:

./target/release/moonbeam --dev

Note

For people not familiar with Substrate, the --dev flag is a way to run a Substrate-based node in a single node developer configuration for testing purposes. You can learn more about --dev in this Substrate tutorial.

You should see an output that looks like the following, showing an idle state waiting for blocks to be produced:

Output shows blocks being produced

For more information on some of the flags and options used in the example, check out Common Flags and Options. If you want to see a complete list of all of the flags, options, and subcommands, open the help menu by running:

./target/release/moonbeam --help

Connecting Polkadot JS Apps to a Local Moonbeam Node

The development node is a Substrate-based node, so you can interact with it using standard Substrate tools. The two provided RPC endpoints are:

  • HTTP: http://127.0.0.1:9933
  • WS: ws://127.0.0.1:9944

Start by connecting to it with Polkadot JS Apps. Open a browser to: https://polkadot.js.org/apps/#/explorer. This will open Polkadot JS Apps, which automatically connects to Polkadot MainNet.

Polkadot JS Apps

Click on the top left corner to open the menu to configure the networks, and then navigate down to open the Development sub-menu. In there, you will want to toggle the "Local Node" option, which points Polkadot JS Apps to ws://127.0.0.1:9944. Next, select the Switch button, and the site should connect to your Moonbeam development node.

Select Local Node

With Polkadot JS Apps connected, you will see the Moonbeam development node waiting for transactions to arrive to begin producing blocks.

Select Local Node

Querying Account State

With the release of Moonbase Alpha v3, Moonbeam now works under a single account format, which is the Ethereum-styled H160 and is now also supported in Polkadot JS Apps. To check the balance of an address, you can simply import your account in the Accounts tab. You can find more information in the Unified Accounts section.

Nevertheless, leveraging the Ethereum full RPC capabilities of Moonbeam, you can use MetaMask to check the balance of that address as well. In addition, you can also use other development tools, such as Remix and Truffle.

Common Commands, Flags and Options

Purging the Chain

When running a node via the binary file, data is stored in a local directory typically located in ~/.local/shared/moonbeam/chains/development/db. If you want to start a fresh instance of the node, you can either delete the content of the folder, or run the following command inside the moonbeam folder:

./target/release/moonbeam purge-chain --dev -y

This will remove the data folder, note that all chain data is now lost.

If you used Docker, the data folder is related to the Docker container itself.

Node Flags

Flags do not take an argument. To use a flag, add it to the end of a command. For example:

./target/release/moonbeam --dev
  • --dev: Specifies the development chain
  • --no-telemetry: Disable connecting to the Substrate telemetry server. For global chains, telemetry is on by default. Telemetry is unavailable if you are running a development (--dev) node.
  • --tmp: Runs a temporary node in which all of the configuration will be deleted at the end of the process
  • --rpc-external: Listen to all RPC interfaces
  • --ws-external: Listen to all Websocket interfaces

Node Options

Options accept an argument to the right side of the option. For example:

./target/release/moonbeam --dev --sealing 6000
  • -l <log pattern> or --log <log pattern>: Sets a custom logging filter. The syntax for the log pattern is <target>=<level>. For example, to print all of the RPC logs, the command would look like this: -l rpc=trace.
  • --sealing <interval>: When blocks should be sealed in the dev service. Accepted arguments for interval: instant, manual, or a number representing the timer interval in milliseconds (for example, 6000 will have the node produce blocks every 6 seconds). The default is instant.
  • --rpc-port <port>: Sets the HTTP RPC server TCP port. Accepts a port as the argument.
  • --ws-port <port>: Sets the WebSockets RPC server TCP port. Accepts a port as the argument.

For a complete list of flags and options, spin up your Moonbeam development node with --help added to the end of the command.

Advanced Flags and Options

With the release of Moonbase Alpha v7, nodes also provide access to some non-standard RPC methods, which allow developers to inspect and debug transactions during runtime. Currently, two features are available:

  • Geth debug API: more specifically, the debug_traceTransaction method. This will attempt to run the transaction in the same manner as it was executed. You can read more about this RPC method in this link
  • OpenEthereum trace module: more specifically, the trace_filter method. This returns the trace matching a specific filter provided as input to the RPC call. You can read more about this RPC method in this link

The features mentioned above can be activated using the following flags:

  • --ethapi=debug: enables the Geth debug API for the debug_traceTransaction RPC call
  • --ethapi=trace: enables the OpenEthereum trace module for the trace_filter RPC call

Note

Debug/Trace features are still being actively developed. Because these requests are very CPU-demanding, it is recommended to run the node with the --execution=Native flag. This will use the native runtime included as part of the node executable instead of the Wasm binary stored on-chain.

You can combine both flags when running a node.

By default, the maximum number of trace entries a single request of trace_filter is allowed to return is 500. A request exceeding this limit will return an error. You can set a different maximum limit with the following flag:

  • --ethapi-trace-max-count <uint>: sets the maximum number of trace entries to be returned by the node

Blocks processed by requests are temporarily stored on cache for a certain amount of time (default is 300 seconds), after which they are deleted. You can set a different time for deletion with the following flag:

  • -ethapi-trace-cache-duration <uint>: sets the duration (in seconds) after which the cache of trace_filter, for a given block, is discarded

For example, when running the binary:

./target/release/moonbeam --dev --execution=Native --ethapi=debug,trace

Pre-funded Development Accounts

Your Moonbeam development node comes with ten pre-funded accounts for development. The addresses are derived from Substrate's canonical development mnemonic:

bottom drive obey lake curtain smoke basket hold race lonely fit walk
  • Alith:

    • Public Address: 0xf24FF3a9CF04c71Dbc94D0b566f7A27B94566cac
    • Private Key: 0x5fb92d6e98884f76de468fa3f6278f8807c48bebc13595d45af5bdc4da702133
  • Baltathar:

    • Public Address: 0x3Cd0A705a2DC65e5b1E1205896BaA2be8A07c6e0
    • Private Key: 0x8075991ce870b93a8870eca0c0f91913d12f47948ca0fd25b49c6fa7cdbeee8b
  • Charleth:

    • Public Address: 0x798d4Ba9baf0064Ec19eB4F0a1a45785ae9D6DFc
    • Private Key: 0x0b6e18cafb6ed99687ec547bd28139cafdd2bffe70e6b688025de6b445aa5c5b
  • Dorothy:

    • Public Address: 0x773539d4Ac0e786233D90A233654ccEE26a613D9
    • Private Key: 0x39539ab1876910bbf3a223d84a29e28f1cb4e2e456503e7e91ed39b2e7223d68
  • Ethan:

    • Public Address: 0xFf64d3F6efE2317EE2807d223a0Bdc4c0c49dfDB
    • Private Key: 0x7dce9bc8babb68fec1409be38c8e1a52650206a7ed90ff956ae8a6d15eeaaef4
  • Faith:

    • Public Address: 0xC0F0f4ab324C46e55D02D0033343B4Be8A55532d
    • Private Key: 0xb9d2ea9a615f3165812e8d44de0d24da9bbd164b65c4f0573e1ce2c8dbd9c8df
  • Goliath:

    • Public Address: 0x7BF369283338E12C90514468aa3868A551AB2929
    • Private Key: 0x96b8a38e12e1a31dee1eab2fffdf9d9990045f5b37e44d8cc27766ef294acf18
  • Heath:

    • Public Address: 0x931f3600a299fd9B24cEfB3BfF79388D19804BeA
    • Private Key: 0x0d6dcaaef49272a5411896be8ad16c01c35d6f8c18873387b71fbc734759b0ab
  • Ida:

    • Public Address: 0xC41C5F1123ECCd5ce233578B2e7ebd5693869d73
    • Private Key: 0x4c42532034540267bf568198ccec4cb822a025da542861fcb146a5fab6433ff8
  • Judith:

    • Public Address: 0x2898FE7a42Be376C8BC7AF536A940F7Fd5aDd423
    • Private Key: 0x94c49300a58d576011096bcb006aa06f5a91b34b4383891e8029c21dc39fbb8b

Checkout the Using MetaMask section to get started interacting with your accounts.

Also, included with the development node is a prefunded account used for testing purposes:

  • Gerald:
    • Public Address: 0x6Be02d1d3665660d22FF9624b7BE0551ee1Ac91b
    • Private Key: 0x99b3c12287537e38c90a9219d4cb074a89a16e9cdb20bf85728ebd97c343e342