Skip to content

Latest commit

 

History

History
424 lines (307 loc) · 14.2 KB

run-keep-node.adoc

File metadata and controls

424 lines (307 loc) · 14.2 KB

Run Keep Node

Table of Contents

System Considerations

The Keep Network expects certain capabilities for each node running on the network. To help attain these capabilities consider the following criteria:

  • It is paramount that Keep nodes remain available to the Keep Network. We strongly encourage a stable and redundant internet connection. See Network section.

  • A connection to a production grade self-hosted or third party Ethereum node deployment. See Ethereum API section.

  • Persistent and redundant storage that will survive a VM or container rotation, and a disk failure. See Persistance section.

  • Each node running on the network requires a unique Ethereum Operator Account. The account has to maintain a positive Ether balance at all times. See Operator Account section.

  • Each node running on the network requires a unique IP address or a unique application port running under the same IP. See Network section.

Recommended Machine Types

Your operating environment will ultimately dictate what machine type to go with. This is particularly relevant if you’re running a containerized solution where multiple applications are sharing VM resources. The below types are sufficient for running at least one instance of the Keep Node.

Cloud Provider Machine Type

Google Cloud

n2-highcpu-2

AWS

c5.large

Azure

F2s v2

Self-hosted

2 vCPU / 2 GiB RAM / 1 GiB Persistent Storage

Starting a Client

Configuration

The client expects configuration options to be specified in a config file or passed as CLI flags. If you specify an option by using a parameter on the command line, it will override the value read from the configuration file.

Operator Account

The client requires an Ethereum Key File of an Operator Account to connect to the Ethereum chain.

The Ethereum Key File is expected to be encrypted with a password. The password has to be provided in a prompt after the client starts or configured as a KEEP_ETHEREUM_PASSWORD environment variable.

The Operator Account has to maintain a positive Ether balance at all times. We strongly advice you monitor the account and top-up when its balance gets below 0,5 Ether.

Ethereum API

A Keep Node requires a connection to a WebSocket Ethereum API. You should obtain a WS API URL from a service provider (e.g. Alchemy, Infura) or run your own Ethereum node (e.g. Geth).

CLI Options

link:./resources/client-start-help[role=include]

Config File

Application configuration can be stored in a file and passed to the application with the --config flag.

Example:

./keep-client --config /path/to/your/config.toml start

Configuration files in formats TOML, YAML and JSON are supported.

Sample configuration file:

link:../configs/config.toml.SAMPLE[role=include]

Persistance

A client will produce and store data on disk. The directory should be provided to the client under storage.Dir (flag: --storage.dir) configuration property.

Warning
 It is crucial to ensure the data directory is persisted and backed up on a regular basis.

There will be two subdirectories created in the storage directory: - keystore, - work.

keystore

The keystore subdirectory contains sensitive key material data generated by the client. Loosing the keystore data is a serious protocol offense and leads to slashing and potentially losing funds.

Important
 It is the operator’s responsibility to ensure the keystore data are not lost under any circumstances.
work

The work directory contains data generated by the client that should persist the client restarts or relocations. If the work data are lost the client will be able to recreate them, but it is inconvenient due to the time needed for the operation to complete and may lead to losing rewards.

Network

The node has to be accessible publicly to establish and maintain connections with bootstrap nodes and discovered peers.

The node exposes metrics and diagnostics services for monitoring.

Ports

A Network Port has to be exposed publicly, so the peers can connect to your node. A Diagnostics Port has to be exposed publicly, for the Rewards Allocation.

Important
 Please update your firewall rules if necessary.
Name Config Property Direction Type Default

Network

network.port

Egress/Ingress

TCP

3919

Client Info

clientInfo.port

Egress

TCP

9601
Announced Addresses

An Announced Address is a layered addressing information (multiaddress/multiaddr) announced to the Keep Network that is used by peers to connect with your node, e.g.: /dns4/bootstrap-0.test.keep.network/tcp/3919 or /ip4/104.154.61.116/tcp/3919.

If the machine you’re running your node is not exposing a public IP (e.g. it is behind NAT) you should set the network.AnnouncedAddresses (flag: --network.announcedAddresses) configuration property to an addresses (ip4 or dns4) under which your node is reachable for the public.

To read more about multiaddress see the libp2p docummentation.

Minimum Required Configuration

The minimum required configuration for the client to start covers setting:

Installation

Build from Source

See our developer docs.

Run

Sample commands to run the Keep Client.

Tip
 Instead of passing the configuration properties as command arguments you can point to a configuration file with --config flag. See Config File section for details.

Binary

link:resources/client-start-mainnet-sample[role=include]

Docker

link:resources/docker-start-mainnet-sample[role=include]

Logging

Configuration

Logging can be configured with environment variables. Please see sample settings:

LOG_LEVEL=DEBUG
IPFS_LOGGING_FMT=nocolor
GOLOG_FILE=/var/log/keep/keep.log
GOLOG_TRACING_FILE=/var/log/keep/trace.json

Startup

Below are some of the key things to look out for to make sure you’re booted and connected to the network:

▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄
▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
  ▓▓▓▓▓▓    ▓▓▓▓▓▓▓▀    ▐▓▓▓▓▓▓    ▐▓▓▓▓▓   ▓▓▓▓▓▓     ▓▓▓▓▓   ▐▓▓▓▓▓▌   ▐▓▓▓▓▓▓
  ▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀      ▐▓▓▓▓▓▓▄▄▄▄         ▓▓▓▓▓▓▄▄▄▄         ▐▓▓▓▓▓▌   ▐▓▓▓▓▓▓
  ▓▓▓▓▓▓▓▓▓▓▓▓▓▀        ▐▓▓▓▓▓▓▓▓▓▓         ▓▓▓▓▓▓▓▓▓▓▌        ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
  ▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄       ▐▓▓▓▓▓▓▀▀▀▀         ▓▓▓▓▓▓▀▀▀▀         ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀
  ▓▓▓▓▓▓   ▀▓▓▓▓▓▓▄     ▐▓▓▓▓▓▓     ▓▓▓▓▓   ▓▓▓▓▓▓     ▓▓▓▓▓   ▐▓▓▓▓▓▌
▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  ▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  ▓▓▓▓▓▓▓▓▓▓

Trust math, not hardware.

------------------------------------------------------------------------------------------------
| Keep Client Node                                                                             |
|                                                                                              |
| Operator: 0x6299496199d99941193Fdd2d717ef585F431eA05                                         |
|                                                                                              |
| Port: 3919                                                                                   |
| IPs : /ip4/127.0.0.1/tcp/3919/ipfs/16Uiu2HAmM2WfE4uwymj9n1EsaN5jL38cG79jCCSXLX49KoL18aZQ     |
|       /ip6/::1/tcp/3919/ipfs/16Uiu2HAmM2WfE4uwymj9n1EsaN5jL38cG79jCCSXLX49KoL18aZQ           |
|       /ip4/192.168.1.167/tcp/3919/ipfs/16Uiu2HAmM2WfE4uwymj9n1EsaN5jL38cG79jCCSXLX49KoL18aZQ |
|       /ip4/10.2.0.2/tcp/3919/ipfs/16Uiu2HAmM2WfE4uwymj9n1EsaN5jL38cG79jCCSXLX49KoL18aZQ      |
|                                                                                              |
| Contracts:                                                                                   |
| RandomBeacon   : 0x2bA82903B635a96154A515488d2952E86D6adc3A                                  |
| WalletRegistry : 0x2363cc10b7680000C02E4a7067A68d1788ffc86F                                  |
| TokenStaking   : 0x69f962a0fbA5635e84eC94131f9072108E2E4F24                                  |
------------------------------------------------------------------------------------------------
Tip
 If you want to share your LibP2P address with others you can get it from the startup log. When sharing remember to substitute the /ipv4/ address with the public facing IP of your client if you’re running on a private machine, or replace the entire /ipv4/ segment with a DNS entry if you’re using a hostname.

Client Info

The client exposes metrics and diagnostics on a configurable port (default: 9601) under /metrics and /diagnostics resources.

The data can be consumed by Prometheus to monitor the state of a node.

Metrics

The client exposes the following metrics:

  • connected peers count,

  • connected bootstraps count,

  • Ethereum client connectivity status (if a simple read-only CALL can be executed).

Metrics are enabled once the client starts. It is possible to customize the port at which metrics endpoint is exposed as well as the frequency with which the metrics are collected.

Exposed metrics contain the value and timestamp at which they were collected.

Example metrics endpoint call result:

$ curl localhost:9601/metrics
# TYPE connected_peers_count gauge
connected_peers_count 108 1623235129569

# TYPE connected_bootstrap_count gauge
connected_bootstrap_count 10 1623235129569

# TYPE eth_connectivity gauge
eth_connectivity 1 1623235129789

Diagnostics

The client exposes the following diagnostics:

  • list of connected peers along with their network id and Ethereum operator address,

  • information about the client’s network id and Ethereum operator address.

Diagnostics are enabled once the client starts. It is possible to customize the port at which diagnostics endpoint is exposed.

Example diagnostics endpoint call result:

$ curl localhost:9601/diagnostics
{
  "client_info" {
   "ethereum_address":"0xDcd4199e22d09248cA2583cBDD2759b2acD22381",
   "network_id":"16Uiu2HAkzYFHsqbwt64ZztWWK1hyeLntRNqWMYFiZjaKu1PZgikN"
  },
  "connected_peers": [
    {"ethereum_address":"0x3712C6fED51CECA83cA953f6FF3458f2339436b4","network_id":"16Uiu2HAkyYtzNoWuF3ULaA7RMfVAxvfQQ9YRvRT3TK4tXmuZtaWi"},
    {"ethereum_address":"0x4bFa10B1538E8E765E995688D8EEc39C717B6797","network_id":"16Uiu2HAm9d4MG4LNrwkFmugD2pX7frm6ZmA4vE3EFAEjk7yaoeLd"},
    {"ethereum_address":"0x650A9eD18Df873cad98C88dcaC8170531cAD2399","network_id":"16Uiu2HAkvjVWogUk2gq6VTNLQdFoSHXYpobJdZyuAYeoWD66e8BD"},
    ...
  ]
}

[flask] Testnet

The Keep Network Testnet environment is running against Ethereum Görli Testnet. To run the client connected to the Testnet add --testnet flag to the start command.

A Docker image for Testnet is published under: us-docker.pkg.dev/keep-test-f3e0/public/keep-client:latest
See Docker section for details.

Bootstrap Nodes

A client running on testnet establishes connection to the following bootstrap nodes:

link:../config/_peers/testnet[role=include]

Contracts

To get adresses of contracts on Testnet please see the link.

Installation

Docker

To get the Docker image run one of the following commands:

  • Latest: us-docker.pkg.dev/keep-test-f3e0/public/keep-client

  • Tagged: us-docker.pkg.dev/keep-test-f3e0/public/keep-client:<tag-version>

Run

Docker

This is a sample run command for illustration purposes only:

link:resources/docker-start-testnet-sample[role=include]