Skip to main content

Run Node from Source

This guide will walk you through deploying an RPC node from the go-flare source code. Building from source gives you more control over the build process and access to the very latest code, but requires managing dependencies manually. Make sure to check the hardware requirements before proceeding.

Prerequisites​

Build the binary​

  1. Retrieve the source code from the latest stable release:

    # 1. Find the latest stable release tag from:
    #    https://github.com/flare-foundation/go-flare/releases
    # 2. Set the tag name in the variable below:
    LATEST_TAG="vX.Y.Z" # <-- REPLACE vX.Y.Z WITH THE ACTUAL LATEST TAG e.g. v1.10.0

  2. Clone and build the binary:

    git clone --branch ${LATEST_TAG} https://github.com/flare-foundation/go-flare.git
    cd go-flare/avalanchego
    ./scripts/build.sh

    The resulting executable will be stored in build/avalanchego.

  3. Verify the installation by running:

    go test $(go list ./... | grep -v /tests/) # avalanchego unit tests
    cd ../coreth
    go test ./... # coreth unit tests
    cd -

Run the node​

  1. The following command is the simplest way to quickly get your node up and running. The next section explains the parameters used here, along with additional parameters you may wish to configure.

    ./build/avalanchego --network-id=flare \
       --http-host= \
       --bootstrap-ips="$(curl -m 10 -sX POST --data '{"jsonrpc":"2.0", "id":1, "method":"info.getNodeIP"}' -H 'content-type:application/json;' https://flare-bootstrap.flare.network/ext/info  | jq -r '.result.ip')" \
       --bootstrap-ids="$(curl -m 10 -sX POST --data '{"jsonrpc":"2.0", "id":1, "method":"info.getNodeID"}' -H 'content-type:application/json;' https://flare-bootstrap.flare.network/ext/info | jq -r '.result.nodeID')"

  2. After a lot of log messages the node should start synchronizing with the network, which might take anywhere from a few hours to a few days depending on the chosen network and hardware specification. Node syncing can be stopped at any time. Use the same command to resume the node syncing from where it left off.

    You will know your node is fully booted and accepting transactions when the output of this command contain the field "healthy" : true in the returned JSON object:

    curl http://127.0.0.1:9650/ext/health | jq
Node stuck when bootstrapping?

If the node gets stuck during bootstrap (or it takes far longer than the estimates given above), try adding the parameter --bootstrap-retry-enabled=false when running the node.

CLI parameters​

These are some of the most relevant CLI parameters you can use. Read more about them in the Avalanche documentation.

  • --bootstrap-ips, --bootstrap-ids: IP address and node ID of the peer used to connect to the rest of the network for bootstrapping. In the run command above, the bootstrap details are programmatically retrieved from the Flare bootstrap nodes upon startup. This is the recommended approach as the bootstrap node's IP and ID can rotate.

  • --http-host: Use --http-host= (empty) to allow connections from other machines. Otherwise, only connections from localhost are accepted.

  • --http-port: The port through which the node will listen to API requests. The default value is 9650.

  • --staking-port: The port through which the network peers will connect to this node externally. Having this port accessible from the internet is required for correct node operation. The default value is 9651.

  • --db-dir: Directory where the database is stored, defaults to ~/.avalanchego/db. Make sure to use a disk with enough space as recommended in the hardware requirements page. For example, you can use this option to store the database on an external drive.

  • --chain-config-dir: Optional JSON configuration file for using non-default values.

Sample JSON configuration:​

<chain-config-dir>/C/config.json
{
  "snowman-api-enabled": false,
  "coreth-admin-api-enabled": false,
  "eth-apis": [
    "eth",
    "eth-filter",
    "net",
    "web3",
    "internal-eth",
    "internal-blockchain",
    "internal-transaction"
  ],
  "rpc-gas-cap": 50000000,
  "rpc-tx-fee-cap": 100,
  "pruning-enabled": true, // Set to false for archival nodes, but requires more disk space
  "local-txs-enabled": false,
  "api-max-duration": 0,
  "api-max-blocks-per-request": 0,
  "allow-unfinalized-queries": false,
  "allow-unprotected-txs": false,
  "remote-tx-gossip-only-enabled": false,
  "log-level": "info"
}

Update the node​

To update your node to a newer version of go-flare:

  1. Stop the running node (e.g., using Ctrl+C if running in the foreground, or via your service manager like systemd).

  2. Navigate to the source directory:

    cd /path/to/go-flare

  3. Fetch the latest changes and checkout the new version:

    git fetch origin
    # 1. Find the latest stable release tag from:
    #    https://github.com/flare-foundation/go-flare/releases
    # 2. Set the tag name in the variable below:
    LATEST_TAG="vX.Y.Z" # <-- REPLACE vX.Y.Z WITH THE ACTUAL LATEST TAG e.g. v1.10.1
    git checkout ${LATEST_TAG}

  4. Rebuild the binary:

    cd go-flare/avalanchego
    ./scripts/build.sh

  5. Restart the node using the same run command and parameters as before.

Maintain the node​

In some cases, your node might not work correctly or you might receive unusual messages that are difficult to troubleshoot. Use the following solutions to ensure your node stays healthy:

  • Ensure Adequate Peers: When your node has fewer than 16 peers, it will not work correctly. To retrieve the number of connected peers, run the following command and look for the line containing connectedPeers:

    curl http://127.0.0.1:9650/ext/health | jq

    To automate the process, use:

    curl -s http://127.0.0.1:9650/ext/health | jq -r ".checks.network.message.connectedPeers"

  • Check Disk Space: If your node does not sync after a long time and abruptly stops working, ensure the database location has sufficient disk space. Remember, the database size might change significantly during bootstrapping.

  • Resolve Connection Issues: If you receive unusual messages after making submissions or when transactions are reverted, your node might not be connected correctly. Ensure the database location has sufficient disk space, then restart the node.

  • Handle Bootstrap Errors: If you receive an error related to GetAcceptedFrontier during bootstrapping, your node was disconnected during the process. Restart the node if you see the following error:

    failed to send GetAcceptedFrontier(MtF8bVH241hetCQJgsKEdKyJBs8vhp1BC, 11111111111111111111111111111111LpoYY, NUMBER)

  • Restart Unhealthy Nodes: If your node syncs but remains unhealthy for no discernible reason, restart the node.