Running an L1 Node for Hypha

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 an L1 node on Fuji testnet and Mainnet.

Component

Fuji Testnet

Mainnet

CPU vCores

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

Contabo
Amazon Web Services (AWS)
OVH
Netcup
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:

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.

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

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.

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:

Stop the AvalancheGo Process

Stop the avalanchego service before making changes:

sudo systemctl stop avalanchego

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?

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

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

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.

Reload and Restart the Service

Reload the systemd configuration and restart the avalanchego service:

sudo systemctl daemon-reload
sudo systemctl start avalanchego

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.

Common Issues and Troubleshooting

This section addresses specific edge cases that can affect Hypha L1 node operation. Review these scenarios and their resolutions if you experience unexpected behavior or issues with your node.

Port Forwarding

Proper port forwarding is essential for your Hypha L1 node to communicate externally. If port 9651 is not correctly forwarded, your node may experience connectivity issues and report low uptime.

Resolution

Ensure that port 9651 is open and accessible from the Internet on the public IP address configured for your node.

Firewall (UFW) Interference

Firewall configurations, such as those using UFW on Ubuntu, can sometimes inadvertently block necessary network traffic for a running Hypha node. This can occur even when other nodes on the same system function correctly.

Resolution

Verify that your firewall is correctly configured to allow inbound and outbound traffic on all required ports for your Hypha node, specifically port 9651. Refer to your operating system's firewall documentation for detailed configuration instructions.

Incorrect IP Configuration

Configuring the publicIP with an IPv6-only address may lead to connectivity problems and impact node uptime.

Resolution

Ensure your node's publicIP is explicitly configured with an IPv4 address. Confirm that port 9651 is correctly forwarded and accessible externally on this IPv4 address.

Staker/Signer File Integrity

The node software may modify or overwrite critical staker and signer files (e.g., staker.crt, staker.key, signer.key) located within the /chainData/staking/ directory. This can result in changes to your Node ID or other operational disruptions.

Resolution

Regularly back up your staker.crt, staker.key, and signer.key files. If these files are suspected of corruption or unintended modification, restore them from a known good backup.

Conclusion

If these steps don’t resolve your problem, refer to the AvalancheGo documentation or reach out to Hypha support for assistance on Discord or via Live Support Chat on the Hypha website.

PreviousHardware Provider Onboarding NextLiquid Staking

Last updated 2 days ago

Running an L1 Node for Hypha

Learn how to run an L1 node.

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 an L1 node on Fuji testnet and Mainnet.

Component

Fuji Testnet

Mainnet

CPU vCores

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.

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

Suggested Hosting Providers

Contabo
Amazon Web Services (AWS)
OVH
Netcup
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:

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?

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

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

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:

Stop the AvalancheGo Process

Stop the avalanchego service before making changes:

sudo systemctl stop avalanchego

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?

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

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

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.

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.

Common Issues and Troubleshooting

This section addresses specific edge cases that can affect Hypha L1 node operation. Review these scenarios and their resolutions if you experience unexpected behavior or issues with your node.

Port Forwarding

Proper port forwarding is essential for your Hypha L1 node to communicate externally. If port 9651 is not correctly forwarded, your node may experience connectivity issues and report low uptime.

Resolution

Ensure that port 9651 is open and accessible from the Internet on the public IP address configured for your node.

Firewall (UFW) Interference

Resolution

Incorrect IP Configuration

Configuring the publicIP with an IPv6-only address may lead to connectivity problems and impact node uptime.

Resolution

Ensure your node's publicIP is explicitly configured with an IPv4 address. Confirm that port 9651 is correctly forwarded and accessible externally on this IPv4 address.

Staker/Signer File Integrity

Resolution

Regularly back up your staker.crt, staker.key, and signer.key files. If these files are suspected of corruption or unintended modification, restore them from a known good backup.

Conclusion

If these steps don’t resolve your problem, refer to the AvalancheGo documentation or reach out to Hypha support for assistance on Discord or via Live Support Chat on the Hypha website.

PreviousHardware Provider Onboarding NextLiquid Staking

Last updated 2 days ago