Skip to content

Getting Started with a Local Moonbeam Development Node

Introduction

A Moonbeam development node is your own personal development environment for building and testing applications on Moonbeam. For Ethereum developers, it is comparable to the Hardhat Network. 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 the default behavior of Hardhat Network's instamine feature.

If you follow this guide to the end, you will have a Moonbeam development node running in your local environment with 10 prefunded accounts.

Note

This tutorial was created using the v0.36.0 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 assume you have a MacOS or Ubuntu 22.04-based environment and will need to be adapted accordingly for Windows.

Spin Up a Moonbeam Development Node

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 node-building 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 development node, it could take roughly 30 minutes or longer to complete, depending on your hardware.

Spin Up a Node with Docker

Using Docker enables you to spin up a node in a matter of seconds. Once you have Docker installed, you can take the following steps to spin up your node:

  1. Execute the following command to download the latest Moonbeam image:

    docker pull moonbeamfoundation/moonbeam:v0.36.0
    

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

    docker pull moonbeamfoundation/moonbeam:v0.36.0
    v0.36.0: Pulling from moonbeamfoundation/moonbeam
    e1caac4eb9d2: Pull complete
    303f0b059437: Pull complete
    1987eeb667a4: Pull complete
    c2b8e919bd5a: Pull complete
    c6a7952896a0: Pull complete
    3ad97e77096a: Pull complete
    a5e5655dbb4f: Pull complete
    Digest: sha256:099e885c4601c8f7ba4408492f2df142920a794baf019cf71cf3a3a16810f504
    Status: Downloaded newer image for moonbeamfoundation/moonbeam:v0.36.0
    docker.io/moonbeamfoundation/moonbeam:v0.36.0

  2. Spin up a Moonbeam development node by running the following Docker command, which will launch the node in instant seal mode for local testing so that blocks are authored instantly as transactions are received:

    docker run --rm --name moonbeam_development --network host \
    moonbeamfoundation/moonbeam:v0.36.0 \
    --dev --rpc-external
    
    docker run --rm --name moonbeam_development -p 9944:9944 \
    moonbeamfoundation/moonbeam:v0.36.0 \
    --dev --rpc-external
    
    docker run --rm --name moonbeam_development -p 9944:9944 ^
    moonbeamfoundation/moonbeam:v0.36.0 ^
    --dev --rpc-external
    

Note

On MacOS with silicon chips, Docker images may perform poorly. To improve performance, try spinning up a Node with a Binary File.

If successful, you should see an output showing an idle state waiting for blocks to be authored:

docker run --rm --name moonbeam_development --network host \
moonbeamfoundation/moonbeam:v0.36.0 \
--dev --rpc-external

CLI parameter `--execution` has no effect anymore and will be removed in the future!
2024-02-27 06:09:29 Moonbeam Parachain Collator
2024-02-27 06:09:29 ✌️ 0.36.0-d1087f30917
2024-02-27 06:09:29 ❤️ by PureStake, 2019-2024
2024-02-27 06:09:29 📋 Chain specification: Moonbase Development Testnet
2024-02-27 06:09:29 🏷 Node name: black-and-white-sticks-9174
2024-02-27 06:09:29 👤 Role: AUTHORITY
2024-02-27 06:09:29 💾 Database: RocksDb at /tmp/substrateO3YeRz/chains/moonbase_dev/db/full
2024-02-27 06:09:40 🔨 Initializing Genesis block/state (state: 0x7c34…99c5, header-hash: 0xa083…f354)
2024-02-27 06:09:40 Using default protocol ID "sup" because none is configured in the chain specs
2024-02-27 06:09:40 🏷 Local node identity is: 12D3KooWLcpczme2JeBEfLqmjqkzYVKTGKhhGmwSzHjRXGBVhDX7
2024-02-27 06:09:40 💻 Operating system: linux
2024-02-27 06:09:40 💻 CPU architecture: x86_64
2024-02-27 06:09:40 💻 Target environment: gnu
2024-02-27 06:09:40 💻 CPU: Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz
2024-02-27 06:09:40 💻 CPU cores: 12
2024-02-27 06:09:40 💻 Memory: 7946MB
2024-02-27 06:09:40 💻 Kernel: 6.4.16-linuxkit
2024-02-27 06:09:40 💻 Linux distribution: Debian GNU/Linux 12 (bookworm)
2024-02-27 06:09:40 💻 Virtual machine: yes
2024-02-27 06:09:40 📦 Highest known block at #0
2024-02-27 06:09:40 Running JSON-RPC server: addr=0.0.0.0:9944, allowed origins=["*"]
2024-02-27 06:09:40 🏁 CPU score: 1.14 GiBs
2024-02-27 06:09:40 〽️ Prometheus exporter started at 127.0.0.1:9615
2024-02-27 06:09:40 🏁 Memory score: 10.41 GiBs
2024-02-27 06:09:40 🏁 Disk score (seq. writes): 987.96 MiBs
2024-02-27 06:09:40 🏁 Disk score (rand. writes): 363.65 MiBs
2024-02-27 06:09:40 Development Service Ready
2024-02-27 06:09:45 💤 Idle (0 peers), best: #0 (0xa083…f354), finalized #0 (0xa083…f354), ⬇ 0 ⬆ 0
2024-02-27 06:09:50 💤 Idle (0 peers), best: #0 (0xa083…f354), finalized #0 (0xa083…f354), ⬇ 0 ⬆ 0

For more information on some of the flags and options used in the example, check out 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 \
moonbeamfoundation/moonbeam \
--help

To continue with the tutorial, the next section is not necessary, as you've already spun up a node with Docker. You can skip ahead to the Configure your Moonbeam Development Node section.

Spin Up a Node with a Binary File

As an alternative to using Docker, you can spin up a node using the Moonbeam binary. This method is more time-consuming. Depending on your hardware, the process could take around 30 minutes to complete.

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 on the system where it will be run.

To build the binary file, you can take the following steps:

  1. Clone a specific tag of the Moonbeam repo, which you can find on the Moonbeam GitHub repository:

    git clone -b v0.36.0 https://github.com/moonbeam-foundation/moonbeam
    cd moonbeam
    

    Note

    Spaces in the installation file path will cause a compilation error.

  2. If you already have Rust installed, you can skip the next two steps. Otherwise, install Rust and its prerequisites via Rust's recommended method by executing:

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    
  3. Update your PATH environment variable by running:

    source $HOME/.cargo/env
    
  4. Build the development node by running:

    Note

    If you are using Ubuntu 20.04 or 22.04, then you will need to make sure these additional dependencies have been installed before building the binary:

    apt install clang protobuf-compiler libprotobuf-dev pkg-config libssl-dev -y 
    

    For MacOS users, these dependencies can be installed via Homebrew:

    brew install llvm
    brew install protobuf
    
    cargo build --release
    

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

    Compiling try-runtime-cli v0.9.0 (https://github.com/paritytech/substrate?branch=rococo-v1#401c24e8)
    Compiling frame-benchmarking-cli v3.0.0 (https://github.com/paritytech/substrate?branch=rococo-v1#401c24e8)
    Compiling cumulus-client-cli v0.1.0 (https://github.com/paritytech/cumulus?branch=rococo-v1#9d89ed65)
    Compiling moonbeam-rpc-txpool v0.6.0 (/home/purestake/moonbeam/client/rpc/txpool)
    Compiling moonbeam-rpc-debug v0.1.0 (/home/purestake/moonbeam/client/rpc/debug)
    Compiling moonbeam-rpc-trace v0.6.0 (/home/purestake/moonbeam/client/rpc/trace)
    Compiling cumulus-client-network v0.1.0 (https://github.com/paritytech/cumulus?branch=rococo-v1#9d89ed65)
    Compiling cumulus-client-consensus-relay-chain v0.1.0 (https://github.com/paritytech/cumulus?branch=rococo-v1#9d89ed65)
    Compiling polkadot-test-service v0.8.29 (https://github.com/paritytech/polkadot?branch=rococo-v1#b64741e6)
    Compiling cumulus-client-collator v0.1.0 (https://github.com/paritytech/cumulus?branch=rococo-v1#9d89ed65)
    Compiling cumulus-client-service v0.1.0 (https://github.com/paritytech/cumulus?branch=rococo-v1#9d89ed65)
    Finished release [optimized] target(s) in 31m 17s

Note

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

Then, you will want to run the node in development 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. When you run your node with the --dev flag, your node is started in a fresh state, and its state does not persist.

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

./target/release/moonbeam --dev
CLI parameter `--execution` has no effect anymore and will be removed in the future!
2024-01-10 06:41:29 Moonbeam Parachain Collator
2024-01-10 06:41:29 ✌️ version 0.35.0-7131ef902c0
2024-01-10 06:41:29 ❤️ by PureStake, 2019-2024
2024-01-10 06:41:29 📋 Chain specification: Moonbase Development Testnet
2024-01-10 06:41:29 🏷 Node name: black-and-white-sticks-9174
2024-01-10 06:41:29 👤 Role: AUTHORITY
2024-01-10 06:41:29 💾 Database: RocksDb at /tmp/substrateO3YeRz/chains/moonbase_dev/db/full
2024-01-10 06:41:40 🔨 Initializing Genesis block/state (state: 0x7c34…99c5, header-hash: 0xa083…f354)
2024-01-10 06:41:40 Using default protocol ID "sup" because none is configured in the chain specs
2024-01-10 06:41:40 🏷 Local node identity is: 12D3KooWLcpczme2JeBEfLqmjqkzYVKTGKhhGmwSzHjRXGBVhDX7
2024-01-10 06:41:40 💻 Operating system: linux
2024-01-10 06:41:40 💻 CPU architecture: x86_64
2024-01-10 06:41:40 💻 Target environment: gnu
2024-01-10 06:41:40 💻 CPU: Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz
2024-01-10 06:41:40 💻 CPU cores: 12
2024-01-10 06:41:40 💻 Memory: 7946MB
2024-01-10 06:41:40 💻 Kernel: 6.4.16-linuxkit
2024-01-10 06:41:40 💻 Linux distribution: Debian GNU/Linux 12 (bookworm)
2024-01-10 06:41:40 💻 Virtual machine: yes
2024-01-10 06:41:40 📦 Highest known block at #0
2024-01-10 06:41:40 Running JSON-RPC server: addr=0.0.0.0:9944, allowed origins=["*"]
2024-01-10 06:41:40 🏁 CPU score: 1.14 GiBs
2024-01-10 06:41:40 〽️ Prometheus exporter started at 127.0.0.1:9615
2024-01-10 06:41:40 🏁 Memory score: 10.41 GiBs
2024-01-10 06:41:40 🏁 Disk score (seq. writes): 987.96 MiBs
2024-01-10 06:41:40 🏁 Disk score (rand. writes): 363.65 MiBs
2024-01-10 06:41:40 Development Service Ready
2024-01-10 06:41:45 💤 Idle (0 peers), best: #0 (0xa083…f354), finalized #0 (0xa083…f354), ⬇ 0 ⬆ 0
2024-01-10 06:41:50 💤 Idle (0 peers), best: #0 (0xa083…f354), finalized #0 (0xa083…f354), ⬇ 0 ⬆ 0

For more information on some of the flags and options used in the example, check out the 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

Configure Your Moonbeam Development Node

Now that you know how to get a standard Moonbeam development node up and running, you may be wondering how you can configure it. The following sections will cover some common configurations you can use when you spin up your node.

Common Flags to Configure Your Node

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
  • --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 and WebSocket interfaces

Common Options to Configure Your Node

Options accept an argument to the right 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 JSON-RPC logs, the command would look like this: -l json=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``. Please refer to the Configure Block Production section below for more information
  • --rpc-port <port> - sets the unified port for HTTP and WS connections. Accepts a port as the argument. Default is 9944
  • --ws-port <port> - deprecated as of client v0.33.0, use --rpc-port for HTTP and WS connections instead - sets the WebSockets RPC server TCP port. As of client v0.30.0, it sets the unified port for both HTTP and WS connections. Accepts a port as the argument
  • --rpc-max-connections <connections> - specifies the combined HTTP and WS connection limit. The default is 100 connections
  • --ws-max-connections <connections> - deprecated as of client v0.33.0, use --rpc-max-connections to limit the HTTP and WS connections instead - this flag adjusts the combined HTTP and WS connection limit. The default is 100 connections
  • --rpc-cors <origins> - specifies the browser origins allowed to access the HTTP and WS RPC servers. The origins can be a comma-separated list of the origins to allow access, or you can also specify null. When running a development node, the default is to allow all origins

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

Configure Block Production

By default, your Moonbeam development node is spun up in instant seal mode, which instantly authors blocks as transactions are received. However, you can specify when blocks should be authored or sealed by using the --sealing option.

The --sealing flag accepts any of the following arguments:

  • instant - as we already covered, this is the default option in which blocks are authored as soon as a transaction is received
  • manual - allows you to produce blocks manually. If a transaction is received, a block will not be produced until you manually create one
  • an interval in milliseconds - authors a block on a specific time interval. For example, if you set it to 6000, you will have the node produce blocks every 6 seconds

The flag should be appended to the start-up command in the following format:

--sealing <interval>

If you choose manual, you'll need to manually create the blocks yourself, which can be done with the engine_createBlock JSON-RPC method:

engine_createBlock(createEmpty: *bool*, finalize: *bool*, parentHash?: *BlockHash*)

For example, you can use the following snippet to manually create a block using Ethers.js, an Ethereum library that makes it easy to interact with JSON-RPC methods:

import { ethers } from 'ethers';

const produceBlock = async () => {
  // Connect to the Ethereum node (if applicable, replace the URL with your node's address)
  const provider = new ethers.JsonRpcProvider(
    'http://127.0.0.1:9944'
  );

  // Set the custom JSON-RPC method and parameters
  const method = 'engine_createBlock';
  const params = [true, true, null];

  try {
    // Send the custom JSON-RPC call
    const result = await provider.send(method, params);
  } catch (error) {
    // Handle any errors that may occur
    console.error('Error:', error.message);
  }
};

produceBlock();

Note

If you're unfamiliar with Ethers, please refer to the Ethers.js documentation page to learn more.

Prefunded Development Accounts

Moonbeam has a unified accounts system, which enables users to have an Ethereum-styled H160 account that can interact with the Substrate API and the Ethereum API. As a result, you can interact with your account through Polkadot.js Apps or MetaMask (or any other EVM wallet). In addition, you can also use other development tools, such as Remix and Hardhat.

Your Moonbeam development node comes with ten prefunded Ethereum-styled 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
Development account addresses and private keys
  • 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

Also included with the development node is an additional prefunded account used for testing purposes:

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

You can connect any of these accounts to MetaMask, Talisman, Polkadot.js Apps, etc., using their private keys.

Development Node Endpoints

You can access your Moonbeam development node using the following RPC and WSS endpoints:

http://127.0.0.1:9944
ws://127.0.0.1:9944

Block Explorers

For a Moonbeam development node, you can use any of the following block explorers:

Debug, Trace, and TxPool APIs

You can also gain access to some non-standard RPC methods by running a tracing node, which allows developers to inspect and debug transactions during runtime. Tracing nodes use a different Docker image than a standard Moonbeam development node.

To learn how to run a Moonbeam development tracing node, check out the Run a Tracing Node guide, and be sure to switch to the Moonbeam Development Node tab throughout the instructions. Then, to access the non-standard RPC methods with your tracing node, check out the Debug & Trace guide.

Purge a Development Node

If you want to remove data associated with your node, you can purge it. The instructions for purging a node are different depending on how you initially spun up your node.

Purge a Node Spun Up with Docker

If you spun up your node using Docker along with the -v flag to specify a mounted directory for your container, you will need to purge that directory. To do so, you can run the following command:

sudo rm -rf /var/lib/alphanet-data/*

If you followed the instructions in this guide and did not use the -v flag, you can stop and remove the Docker container. The associated data will be removed along with it. To do so, you can run the following command:

sudo docker stop `CONTAINER_ID` && docker rm `CONTAINER_ID`

Purge a Node Spun up with a Binary File

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. To learn more about all of the available purge-chain commands, you can check out the Purging Binary Data section of our documentation.

Last update: January 31, 2024
| Created: June 29, 2020