🐻⛓️ Berachain Docs

Appearance

Run Local Validator Node ​

This page will walkthrough everything you need to start running your very own Berachain node, from start to finish.

WARNING

NOTE: The ability to run a Testnet Validator Node will be made public closer to Mainnet. Currently this section for untile the source code and binaries are made available.

System Requirements ​

Before starting the setup process, please check that your machine meets the following requirements.

Minimum Requirements: ​

  • OS: linux
  • CPU Architecture: amd64 or arm64
  • CPU: 4 cores
  • RAM: 16GB
  • Storage: 500GB

TIP

​Certain node configurations may need different configurations, however this is a good baseline for most node configurations.

Releases ​

There are multiple types of releases available for the Berachain node:

  • Binary
  • Docker
  • Building from source

WARNING

Currently, only the binary method is recommended. Docker and building from source will be available in the future.

Binary ​

The binary is a built executable that is fully ready to run a node.

Download the binary from the Berachain Github Release page (Coming Soon).

Add the binary in your path so that you can use the berad command from anywhere in your shell.

shell
# PLEASE NOTE: The Binary is not currently available.
mv <path_to_berad_download> /usr/local/bin/berad;
# PLEASE NOTE: The Binary is not currently available.
mv <path_to_berad_download> /usr/local/bin/berad;

Docker ​

If you prefer, you can also run your Berachain node as a docker container. This can be done using the following command which will download the Berachain node docker image from Amazon's Elastic Container Registry and run it:

shell
# PLEASE NOTE: Docker is not currently available
docker run -d -p 8545:8545 registry.domain/berad/seed:amd-latest bash -c "cd scripts/ && ./start-1-node-testnet.sh";
# PLEASE NOTE: Docker is not currently available
docker run -d -p 8545:8545 registry.domain/berad/seed:amd-latest bash -c "cd scripts/ && ./start-1-node-testnet.sh";

Building from source ​

Please follow the installation process in the Berachain repository.

shell
# PLEASE NOTE: Source will be made available closer to Public Mainnet
git clone https://github.com/berachain/berachain
cd berachain
# PLEASE NOTE: Source will be made available closer to Public Mainnet
git clone https://github.com/berachain/berachain
cd berachain

Running Berachain Node ​

Once you have a the berad binary created, these are the steps to get things up and running.

Step 1 - Initializing the Node ​

bash
# FROM: /your/path/to/berad;

# NOTE: make sure you set proper permission on the file `chmod +x` to allow for usage
# additionally you can specify the config directory with this flag `--home /path/to/.berad`
berad init <MONIKER> --chain-id <CHAINID>; # Ex: berad init beraBeraBananaBoBera --chain-id 123456789


# [Expected Output]:
# {
#  "moniker": "beraBeraBananaBoBera",
# ...
# FROM: /your/path/to/berad;

# NOTE: make sure you set proper permission on the file `chmod +x` to allow for usage
# additionally you can specify the config directory with this flag `--home /path/to/.berad`
berad init <MONIKER> --chain-id <CHAINID>; # Ex: berad init beraBeraBananaBoBera --chain-id 123456789


# [Expected Output]:
# {
#  "moniker": "beraBeraBananaBoBera",
# ...
  • The MONIKER is a custom human readable name for this node
  • The chain ID flag is the chain ID of whichever Berachain Network you're connecting to.

This command will create the following config files in your --home directory. Note that the default home directory is ~/.berad

If successful, you should see the newly created ./berad directory created will the following files.

bash
# FROM: /your/path/to/.berad;

.                                   # ~/.berad
  |- data                           # Contains the databases used by the node.
  |- config/
      |- app.toml                   # Application-related configuration file.
      |- config.toml                # CometBFT-related configuration file.
      |- genesis.json               # The genesis file.
      |- node_key.json              # Private key to use for node authentication in the p2p protocol.
      |- priv_validator_key.json    # Private key to use as a validator in the consensus protocol.
# FROM: /your/path/to/.berad;

.                                   # ~/.berad
  |- data                           # Contains the databases used by the node.
  |- config/
      |- app.toml                   # Application-related configuration file.
      |- config.toml                # CometBFT-related configuration file.
      |- genesis.json               # The genesis file.
      |- node_key.json              # Private key to use for node authentication in the p2p protocol.
      |- priv_validator_key.json    # Private key to use as a validator in the consensus protocol.

Step 2 - Config Genesis File ​

The genesis.json file is a configuration file used in blockchain networks. It serves as the starting point of the blockchain, defining the initial state of the blockchain before any blocks are mined.

The genesis.json can be found in the berachain/node-config repository.

bash
# FROM: /your/path/to/.berad/config;

# remove existing genesis.json
rm genesis.json;

# download new genesis.json file from node-config repository
curl -o genesis.json https://raw.githubusercontent.com/berachain/node-config/main/networks/closed-testnet/genesis/genesis.json;

# (Optional) - in case json isn't formatted correctly
# jq . genesis.json > genesis.formatted.json; rm genesis.json; mv genesis.formatted.json genesis.json;
# FROM: /your/path/to/.berad/config;

# remove existing genesis.json
rm genesis.json;

# download new genesis.json file from node-config repository
curl -o genesis.json https://raw.githubusercontent.com/berachain/node-config/main/networks/closed-testnet/genesis/genesis.json;

# (Optional) - in case json isn't formatted correctly
# jq . genesis.json > genesis.formatted.json; rm genesis.json; mv genesis.formatted.json genesis.json;

Step 3 - Configure Toml Files ​

The app.toml and config.toml can be found in the berachain/node-config repository.

bash
# FROM: /your/path/to/.berad/config;

# remove existing app.toml and config.toml
rm app.toml config.toml;

# download app.toml
curl -o app.toml https://raw.githubusercontent.com/berachain/node-config/main/networks/closed-testnet/archive/config/app.toml;

# download config.toml
curl -o config.toml https://raw.githubusercontent.com/berachain/node-config/main/networks/closed-testnet/archive/config/config.toml;
# FROM: /your/path/to/.berad/config;

# remove existing app.toml and config.toml
rm app.toml config.toml;

# download app.toml
curl -o app.toml https://raw.githubusercontent.com/berachain/node-config/main/networks/closed-testnet/archive/config/app.toml;

# download config.toml
curl -o config.toml https://raw.githubusercontent.com/berachain/node-config/main/networks/closed-testnet/archive/config/config.toml;

Make these adjustments based on your requirements:

  • Modify your app.toml for configs like pruning, api, etc.
  • Modify your config.toml for configs like moniker, ports, etc.

Set seed node addresses in config.toml by looking for this section and pasting in between the quotes the full comma separated addresses:

WARNING

Currently seeds are not provided. It will be added closer to testnet.

File: /your/path/to/.berad/config/config.toml

toml
# ...

# Comma separated list of seed nodes to connect to
seeds = ""

# Example
# seeds = "abcd12345@some.example-domain.xyz:123456789,efghi56789@some.example-domain.xyz:123456789"

# ...
# ...

# Comma separated list of seed nodes to connect to
seeds = ""

# Example
# seeds = "abcd12345@some.example-domain.xyz:123456789,efghi56789@some.example-domain.xyz:123456789"

# ...

Step 4 - Start the Node ​

Start the node by running:

TIP

If syncing your node for the first time, you may be interested in faster syncing options by following the Syncing Your Node Instructions

bash
# FROM: /your/path/to/berad;

./berad start;

# [Expected Output]:
# (THIS SHOULD BE GOING REALLY FAST)
# ...
# 8:37AM INF ...
# 8:37AM INF ...
# FROM: /your/path/to/berad;

./berad start;

# [Expected Output]:
# (THIS SHOULD BE GOING REALLY FAST)
# ...
# 8:37AM INF ...
# 8:37AM INF ...

Test that your node is up and running correctly by performing an RPC request.

Open up another terminal, that has access to the node, and run the following:

bash
# FROM: /any/path/doesnt/matter;

curl -X POST -H "Content-Type: application/json" -d '{
    "jsonrpc":"2.0",
    "method": "eth_blockNumber",
    "params": [],
    "id": 1
}
' http://localhost:8545;

# [Expected Output]:
# {"jsonrpc":"2.0","id":1,"result":"0x7e8"}
# FROM: /any/path/doesnt/matter;

curl -X POST -H "Content-Type: application/json" -d '{
    "jsonrpc":"2.0",
    "method": "eth_blockNumber",
    "params": [],
    "id": 1
}
' http://localhost:8545;

# [Expected Output]:
# {"jsonrpc":"2.0","id":1,"result":"0x7e8"}

Next Steps ​

You now have a fully working full node! However, there may be additional features you wish to use beyond what is supported in the default settings.

If you'd like to setup a keyring to sign blocks & send transactions see the Setting Up Keyring Instructions Page.

If you'd like to see specific what use cases there are for nodes and how to set them up you can check out the Types of Nodes.