Running an Umbrella Validator

In this section, we'll explain the requirements and basics for running your own Umbrella validator node.

Minimum Hardware requirements

Umbrella Network validator node is light. The only heavy part is you'll need a blockchain node connection. But If you use a 3rd party for this (defined below), you can use a server with the following requirements:

CPU: 2
RAM: 2GB (recommended: 4GB)
Storage: 20GB

Using Docker

It's recommended to run the Umbrella validator node with Docker. This is because we continuously build and deploy the code from our repository on Github, which means you don't need a complete development environment to run a node. Right below we show how to run docker containers. For the production environment, we recommend running it via a container orchestrator, such as Kubernetes.

Requirements

  • Install and setup Docker
curl -sSL https://get.docker.com/ | sh
sudo usermod -aG docker $USER
exit
# log in again
# please see https://docs.docker.com/docker-for-mac/install/
sudo amazon-linux-extras install -y docker
sudo systemctl start docker
sudo gpasswd -a $USER docker
exit
# log in again
curl -sSL https://get.docker.com/ | sh
sudo systemctl enable docker
sudo systemctl start docker
sudo usermod -aG docker $USER
exit
# log in again
curl -sSL https://get.docker.com/ | sh
sudo usermod -aG docker $USER
exit
# log in again
curl -sSL https://get.docker.com/ | sh
sudo systemctl start docker
sudo usermod -aG docker $USER
exit
# log in again

📘

Make sure your node is publicly available

All Umbrella nodes need to be available via the Internet. Please make sure the new node can be accessed via an external IP or via DNS.

Create a Directory

Once you have your Ethereum client ready and configured, you're ready to run the Umbrella validator node.

Create a local directory to hold the Umbrella data:

mkdir ~/.umbrella

Creating a network interface

docker network create umbrella-network

Running dependencies locally via Docker

You will need to connect your Umbrella validator to with a MongoDB database and a Redis instance. This can be done via docker.

docker volume create validator-mongodb-data
docker run --restart unless-stopped --name validator-mongodb --network umbrella-network -v validator-mongodb-data:/data/db -d mongo

Check if the MongoDB container is running:

docker ps | grep validator-mongodb

Start Redis:

docker volume create validator-redis-data
docker run --restart unless-stopped --name validator-redis --network umbrella-network -v validator-redis-data:/data/redis -d redis

Check if the Redis container is running:

docker ps | grep validator-redis

Obtain an Ethereum RPC endpoint

You are free to run your own Ethereum node for an RPC endpoint Ethereum node or use a service such as POKT, Infura, or Alchemy to obtain an RPC endpoint.

Create an Environment File

Run the following as a command to create an environment file and populate with variables specific to the network you're running on. For a full list of available configuration variables, see the Configuration Variables page.

Please change it accordingly.

echo 'PORT=3000
ENVIRONMENT=production
NODE_ENV=production
REDIS_URL=redis://validator-redis:6379
MONGODB_URL=mongodb://validator-mongodb:27017/pegasus
BLOCKCHAIN_PROVIDER_URL=https://bsc-dataseed2.defibit.io/
REGISTRY_CONTRACT_ADDRESS=0xb2C6c4162c0d2B6963C62A9133331b4D0359AA34
BLOCK_CREATION_JOB_INTERVAL=1000
POLYGON_IO_TIMEOUT=20000
SIGNATURE_TIMEOUT=30000
STATUS_CHECK_TIMEOUT=5000
UNISWAP_SCANNER_CONTRACT_ID=0x1F98431c8aD98523631AE4a59f267346ea31F984
UNISWAP_HELPER_CONTRACT_ID=0xe44e31361af51d8980f394867e81C7857a188dE8
UNISWAP_START_BLOCK=12369621
APPLICATION_AUTO_UPDATE_ENABLED=true
APPLICATION_AUTO_UPDATE_URL=https://raw.github.com/umbrella-network/pegasus-feeds/main/prod/bsc/ota/manifest.json
APPLICATION_AUTO_UPDATE_INTERVAL=1800000
CONSENSUS_STRATEGY=optimized
BLOCKCHAIN_PROVIDER_0_NAME=eth-mainnet
AVALANCHE_REGISTRY_CONTRACT_ADDRESS=0xDa9A63D77406faa09d265413F4E128B54b5057e0
AVALANCHE_BLOCKCHAIN_PROVIDER_URL=
AVALANCHE_BALANCE_WARN='1.0'
AVALANCHE_BALANCE_ERROR='0.01'
POLYGON_REGISTRY_CONTRACT_ADDRESS=0x455acbbC2c15c086978083968a69B2e7E4d38d34
POLYGON_BLOCKCHAIN_PROVIDER_URL=
POLYGON_BALANCE_WARN='1.0'
POLYGON_BALANCE_ERROR='0.03'

### API provider/keys
BLOCKCHAIN_PROVIDER_0_URL=
BLOCKCHAINS_ETHEREUM_PROVIDER_URL=
VALIDATOR_PRIVATE_KEY=
CRYPTOCOMPARE_API_KEY=
COINMARKETCAP_API_KEY=
GENESIS_VOLATILITY_API_KEY=
POLYGON_IO_API_KEY=
OPTIONS_PRICE_API_KEY=
NAME=validator' > ~/.umbrella/.env

🚧

REDIS_URL

Only use REDIS_URL=redis://validator-redis:6379 if you started a Redis container via Docker in the previous step. Otherwise, please set REDIS_URL to the desired Redis external endpoint.

🚧

MONGODB_URL

Only use MONGODB_URL=mongodb://validator-mongodb:27017/pegasus if you started a MongoDB container via Docker in the previous step. Otherwise, please set MONGODB_URL to the desired MongoDB external endpoint.

🚧

BLOCKCHAIN_PROVIDER_URL

BLOCKCHAIN_PROVIDER_URL=[url]

see https://docs.binance.org/smart-chain/developer/rpc.html for available for available BSC RPCs

🚧

ENVIRONMENT

This is used only as info in /info endpoint.

🚧

NAME

This is used only as info in /info endpoint.

Start the Umbrella validator node

Now you can run the Docker image. Replace with your desired version. Tag versions are available in the Umbrella Docker Hub.

❗️

Docker Image access

At the moment our docker image for validator is private. Please send us your Dockerhub username so that we can grant you as access to the image.

cd ~/.umbrella

# use your Dockerhub credentials to log in
docker login

# start the API
docker run -d --restart unless-stopped --name validator-api --env-file=.env -p 3000:3000 --network umbrella-network umbrellanetwork/pegasus node dist/server.js

# start the Scheduler
docker run -d --restart unless-stopped --name validator-scheduler --env-file=.env --network umbrella-network umbrellanetwork/pegasus node dist/scheduler.js

# start the Worker
docker run -d --restart unless-stopped --name validator-worker --env-file=.env --network umbrella-network umbrellanetwork/pegasus node --max_old_space_size=8192 
 dist/worker.js --worker BlockMintingWorker

#start the dispatcher
docker run -d --restart unless-stopped --name validator-dispatcher-worker --env-file=.env --network umbrella-network umbrellanetwork/pegasus node 
 --max_old_space_size=8192 dist/worker.js --worker BlockDispatcherWorker

# start the Agent 
docker run -d --restart unless-stopped --name validator-agent --env-file=.env --network umbrella-network umbrellanetwork/pegasus node dist/agent.js

# start the metrics worker
docker run -d --restart unless-stopped --name validator-metrics-worker --env-file=.env --network umbrella-network umbrellanetwork/pegasus node --max_old_space_size=8192 dist/worker.js --worker MetricsWorker

# start the Deviation Worker
docker run -d --restart unless-stopped --name deviation-leader-worker --env-file=.env --network umbrella-network umbrellanetwork/pegasus node --max_old_space_size=8192 dist/worker.js --worker DeviationLeaderWorker

Please make sure all the desired containers are running:

docker ps | grep validator

You may see a list of running containers.

docker ps | grep validator

CONTAINER ID   IMAGE                     COMMAND                  STATUS                           PORTS       NAMES        
46e3953cfe3b   umbrellanetwork/pegasus   "docker-entrypoint.s…"   5 minutes ago    Up 5 minutes                validator-dispatcher-worker
0cbd622c7988   umbrellanetwork/pegasus   "docker-entrypoint.s…"   10 minutes ago   Up 10 minutes               validator-agent
edc7c69f1d24   umbrellanetwork/pegasus   "docker-entrypoint.s…"   11 minutes ago   Up 11 minutes               validator-worker
832e72511f21   umbrellanetwork/pegasus   "docker-entrypoint.s…"   13 minutes ago   Up 13 minutes               validator-scheduler
1261d0d22e2c   umbrellanetwork/pegasus   "docker-entrypoint.s…"   13 minutes ago   Up 13 minutes               validator-api
dd6466447d3a   redis                     "docker-entrypoint.s…"   15 minutes ago   Up 15 minutes   6379/tcp    validator-redis
6e914ce0df17   mongo                     "docker-entrypoint.s…"   17 minutes ago   Up 17 minutes   27017/tcp   validator-mongodb

You can check logs for each container above by using the container name.

# logs for the API
docker logs validator-api -f

# logs for the Scheduler
docker logs validator-scheduler -f

# logs for the Worker
docker logs validator-worker -f

# logs for the dispatcher
docker logs validator-dispatcher-worker -f

# logs for the Agent
docker logs validator-agent -f

To confirm you successfully setup your validator, you should see this logs in worker:

info: WS started
warn: WS connecting...
info: BlockMintingWorker job run at 2021-03-24T11:57:26.327Z
info: WS opened
info: Current leader: 0xDc3eBc37DA53A644D67E5E3b5BA4EEF88D969d5C, false
info: BlockMintingWorker job run at 2021-03-24T11:57:30.305Z
info: Current leader: 0xDc3eBc37DA53A644D67E5E3b5BA4EEF88D969d5C, false
info: BlockMintingWorker job run at 2021-03-24T11:57:35.306Z
info: Current leader: 0xDc3eBc37DA53A644D67E5E3b5BA4EEF88D969d5C, false
...

📘

Check the validator status

When you finish, use [validator-url-or-ip]/info endpoint to check your validator status. There should be no errors there.