Running an L1 Node for L1Marketplace

Learn how to run an L1 node.

This guide is part of a series covering the end-to-end process for participating in a Layer 1 blockchain as a hardware provider. It focuses on setting up and running a node using AvalancheGo on any Avalanche-based L1.

This guide is intended for developers familiar with Linux-based systems and command-line operations.

This guide is specifically for hardware providers. If you’re looking to become a validator by staking, refer to the dedicated validator staking guide.

---

Hardware Requirements

Below are the minimum hardware specifications for running a Coqnet node on Fuji testnet and Mainnet.

Component	Fuji Testnet	Mainnet
CPU vCores	4 (2 dedicated)	4 (2 dedicated)
RAM	4GB	8GB
Storage	200GB SSD	300GB SSD
Network In/Out	100Mb/100Mb	5Gb/5Gb
Operating System	Ubuntu 22.04 LTS	Ubuntu 24.04 LTS

While ARM64 binaries are available, we recommend using x86 (AMD64) for stability and performance with most Avalanche-based L1 nodes at this time.

These are baseline numbers for getting started today and are subject to change since storage, CPU, and memory requirements will increase as the blockchain grows. Nearly half of the recommended storage is allocated for the P-Chain.

Using a system that can be easily expanded is highly recommended.

---

Suggested Hosting Providers

• Akamai Connected Cloud (formerly Linode)
• Contabo
• Amazon Web Services (AWS)
• Other cloud providers or dedicated server providers meeting the hardware requirements.

---

Installing AvalancheGo

The first step is installing AvalancheGo, the client software for running L1 nodes. You can install it either manually or via the install script.

Before installing AvalancheGo via your preferred method, we recommend you read on below for your respective install method.

Once AvalancheGo is installed, proceed to configure your node using one of the methods below.

---

Manual Installation Steps

Finding L1 Specific Information

You can find L1 specific information like subnet_ID and VM_ID by finding the L1 here.

If you installed AvalancheGo manually, follow these steps to configure your node:

1

Download and Install the Subnet EVM Binary

Before we can start our node, we need to add the Subnet EVM binary to the machine.

Run the following commands to download and place the Subnet EVM binary in the correct directory.

Be sure to replace <VM_ID> with the actual VM ID for your Subnet before running the command.

# Fetch the latest release download URL and download the tarball
curl -s https://api.github.com/repos/ava-labs/subnet-evm/releases/latest | jq -r '.assets[] | select(.name | test("^subnet-evm_[0-9.]+_linux_amd64\\.tar\\.gz$")) | .browser_download_url' | xargs curl -L -O

# Create the plugins directory if it doesn't exist
mkdir -p "$HOME/.avalanchego/plugins"

# Extract the subnet-evm binary from the tarball
tar -xzf subnet-evm_*_linux_amd64.tar.gz subnet-evm

# Move the extracted binary to the plugins directory with a new name
// highlight-next-line
mv subnet-evm "$HOME/.avalanchego/plugins/"

# Optionally, clean up the downloaded tarball
rm subnet-evm_*_linux_amd64.tar.gz

Configuration Details: VM ID

The VM ID is a cryptographic hash that uniquely identifies the Subnet EVM binary. AvalancheGo uses this ID to locate and execute the correct virtual machine for your Subnet.

How to Find the Correct VM ID?

You can find the correct VM ID (e.g., knwdavfavsrcds7PKZmVBd51ZGxkhRQsC9xUHzSNHdegDCWBL) on the L1's Avalanche Subnet Explorer under the Chain Info section, or in the official documentation provided by your L1 project.

Using the wrong VM ID will prevent connection to your intended blockchain.

2

Configure AvalancheGo Startup

Before starting the node, add the -partial-sync-primary-network flag and the -track-subnets flag with your target L1's Subnet ID to the startup command.

Your startup command should look like this:

Make sure to replace <VERSION> and <Subnet_ID> with the correct AvalancheGo version and your specific Subnet ID before running the command.

./avalanchego--linux/avalanchego --partial-sync-primary-network --track-subnets=

For more details on available configurations, see the AvalancheGo Configs and Flags documentation.

Configuration Details: Subnet ID & Network

<Subnet_ID>: This is the unique identifier for the L1 blockchain (Subnet) you want your node to track and validate.

Examples:

• Coqnet: 5moznRzaAEhzWkNTQVdT1U4Kb9EU7dbsKZQNmHwtN5MGVQRyT

• COQnet Fuji Testnet: 4YurNFwLzhGUrYyihDnUUc2L199YBnFeWP3fhJKmDDjkbvy8G

3

Run at Startup

Configure this command to run automatically at startup using your preferred method (e.g., systemd, supervisor). This ensures your node restarts if the server reboots.

And that's it! 🎉 Your node should now be running and tracking the specified L1 Subnet. You now have a working L1 node running on Avalanche Mainnet.

Remember that it can take a significant amount of time for your node to fully sync with the Primary Network and the tracked Subnet.

---

Finding L1 Specific Information

You can find L1 specific information like subnet_ID and VM_ID by finding the L1 here.

Script Installation Steps

If you used the AvalancheGo install script, follow these steps to configure your node:

1

Stop the AvalancheGo Process

Stop the avalanchego service before making changes:

sudo systemctl stop avalanchego

2

Download and Install the Subnet EVM Binary

Run the following commands to download and place the Subnet EVM binary in the correct directory:

Be sure to replace <VM_ID> with the actual VM ID for your Subnet before running the command.

# Fetch the latest release download URL and download the tarball
curl -s https://api.github.com/repos/ava-labs/subnet-evm/releases/latest | jq -r '.assets[] | select(.name | test("^subnet-evm_[0-9.]+_linux_amd64\\.tar\\.gz$")) | .browser_download_url' | xargs curl -L -O

# Create the plugins directory if it doesn't exist
mkdir -p "$HOME/.avalanchego/plugins"

# Extract the subnet-evm binary from the tarball
tar -xzf subnet-evm_*_linux_amd64.tar.gz subnet-evm

# Move the extracted binary to the plugins directory with a new name
mv subnet-evm "$HOME/.avalanchego/plugins/"

# Optionally, clean up the downloaded tarball
rm subnet-evm_*_linux_amd64.tar.gz

Configuration Details: VM ID

The VM ID is a cryptographic hash that uniquely identifies the Subnet EVM binary. AvalancheGo uses this ID to locate and execute the correct virtual machine for your Subnet.

How to Find the Correct VM ID?

You can find the correct VM ID (e.g., knwdavfavsrcds7PKZmVBd51ZGxkhRQsC9xUHzSNHdegDCWBL) on the L1's Avalanche Subnet Explorer under the Chain Info section, or in the official documentation provided by your L1 project.

Using the wrong VM ID will prevent connection to your intended blockchain.

3

Configure Tracked Subnets

Add the Subnet ID of the L1 to the AvalancheGo configuration file. This file is typically located at $HOME/.avalanchego/configs/node.json.

Be sure to replace <Subnet_ID> with the actual Subnet ID you intend to track before running the command.

{
    "track-subnets": "",
    // ... other existing configurations ...
}

Configuration Details: Subnet ID & Network

Subnet_ID: This is the unique identifier for the L1 blockchain (Subnet) you want your node to track and validate.

Examples:

• Coqnet: 5moznRzaAEhzWkNTQVdT1U4Kb9EU7dbsKZQNmHwtN5MGVQRyT

• COQnet Fuji Testnet: 4YurNFwLzhGUrYyihDnUUc2L199YBnFeWP3fhJKmDDjkbvy8G

4

Enable Partial Sync in the Unit File

It's highly recommended to enable the -partial-sync-primary-network flag. This prevents your node from downloading the full history of the Avalanche C-Chain, saving considerable storage space.

Edit the unit file located at /etc/systemd/system/avalanchego.service to include the --partial-sync-primary-network flag.

Simply add the --partial-sync-primary-network flag to the ExecStart command in the [Service] section.

-ExecStart=/path/to/avalanchego --config-file=/path/to/.avalanchego/configs/node.json
+ExecStart=/path/to/avalanchego --config-file=/path/to/.avalanchego/configs/node.json --partial-sync-primary-network

The updated file should look like this:

[Unit]
Description=AvalancheGo systemd service
StartLimitIntervalSec=0

[Service]
Type=simple
User=ubuntu # Replace with the user running avalanchego
WorkingDirectory=/home/ubuntu # Replace with the user's home or avalanchego directory
ExecStart=/home/ubuntu/avalanche-node/avalanchego --config-file=/home/ubuntu/.avalanchego/configs/node.json --partial-sync-primary-network
LimitNOFILE=32768
Restart=always
RestartSec=1

[Install]
WantedBy=multi-user.target

Be sure to replace ubuntu in User, WorkingDirectory, and ExecStart with the correct username and paths for your system.

5

Reload and Restart the Service

Reload the systemd configuration and restart the avalanchego service:

sudo systemctl daemon-reload
sudo systemctl start avalanchego

And that's it! 🎉 Your node should now be running and tracking the specified L1 Subnet. You now have a working L1 node running on Avalanche Mainnet.

---

Monitoring Your Node

Once your node is running, you can monitor its status and check logs with the following commands:

sudo systemctl status avalanchego
journalctl -u avalanchego -f

Checking Sync Progress

To check if your node has finished bootstrapping (syncing) with the Avalanche Primary Network (P-Chain), you can execute the following command.

curl -X POST -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"info.isBootstrapped","params":{"chain":"P"}}' 127.0.0.1:9650/ext/info

To check the bootstrapping status of your specific L1 Subnet, replace the chain parameter with your L1's Chain ID (not the Subnet ID).

Configuration Details: Chain Alias/ID for Bootstrapping Check

• Primary Network P-Chain (General): Use "P" or the P-Chain's actual ID (e.g., 11111111111111111111111111111111LpoYY for Mainnet and Fuji).

• L1 Subnet's Chain: You'll need the chainID(or Blockchain ID) of your L1. This is different from the Subnet ID.

Example:

• {"chain":"23aQU1537YseCJmXW11XHjPra6bptBSps5D4xXupt8hN2QUeaG"}

• {"chain":"[Your_L1_Chain_ID]"}

A response of "isBootstrapped":true} indicates the chain is bootstrapped.

Conclusion

If you encounter any issues, refer to the AvalancheGo documentation or reach out to Hypha support for assistance on Discord or via Live Support Chat on the Hypha website.