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.

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.41.0
   

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

   docker pull moonbeamfoundation/moonbeam:v0.40.1
   v0.40.1: Pulling from moonbeamfoundation/moonbeam
   b0a0cf830b12: Pull complete
   fbff687640dd: Pull complete
   58ea427410e2: Pull complete
   811ba55e6e61: Pull complete
   4316d5f1b914: Pull complete
   128693ce218e: Pull complete
   a3ac90b88463: Pull complete
   Digest: sha256:5f993e9445da4ca7ae7eaf28ee80b21b7a4cec4341aa75c10c5a9baed41de1a6
   Status: Downloaded newer image for moonbeamfoundation/moonbeam:v0.40.1
   docker.io/moonbeamfoundation/moonbeam:v0.40.1

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:

   UbuntuMacOSWindows

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

   docker run --rm --name moonbeam_development -p 9944:9944 \
   moonbeamfoundation/moonbeam:v0.41.0 \
   --dev --rpc-external
   

   docker run --rm --name moonbeam_development -p 9944:9944 ^
   moonbeamfoundation/moonbeam:v0.41.0 ^
   --dev --rpc-external
   

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

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.

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.41.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

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

./target/release/moonbeam --dev

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

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();

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

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:

• Substrate API — Polkadot.js Apps on WS port 9944
• Ethereum API JSON-RPC-based — Moonbeam Basic Explorer on HTTP port 9944

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.