1. System Considerations

The Keep Network expects certain capabilites 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.

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

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

  • Each random beacon client running on the network requires a unique Ethereum operator account.

  • Each random beacon client running on the network requires a unique IP address or a unique application port running under the same IP.

  • Recommended machine types by provider:

Cloud Provider Machine Type

Google Cloud

n1-standard-2

AWS

m5.large

Azure

D2s v3

Self-hosted

2 vCPU / 4 GiB RAM / 1 GiB Persistent Storage

2. Configuration

2.1. Network

Default port mappings.

Egress Port

Ethereum Network

8545 / 8546

Keep Network

3919

Ingress Port

Keep Network

3919

If you set a different port in your keep-client configuration, or configure peers with non-default ports configured, firewall rules will need to be adjusted accordingly.

2.2. Application

Application configurations are stored in a .toml file and passed to the application run command with the --config flag.

2.2.1. Sample

# Ethereum host connection info.
[ethereum]
  URL = "ws://127.0.0.1:8546"
  URLRPC = "http://127.0.0.1:8545"

# Keep operator Ethereum account.
[ethereum.account]
  Address = "0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA8AAAAAAAAA"
  KeyFile = "/Users/someuser/ethereum/data/keystore/UTC--2018-03-11T01-37-33.202765887Z--AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA8AAAAAAAAA"

# Keep contract addresses configuration.
[ethereum.ContractAddresses]
  # Hex-encoded address of KeepRandomBeaconOperator contract
  KeepRandomBeaconOperator = "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"
  # Hex-encoded address of TokenStaking contract
  TokenStaking = "0xCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC"
  # Hex-encoded address of KeepRandomBeaconService contract. Only needed
  # in cases where the client's utility functions will be used (e.g., the
  # relay subcommand).
  KeepRandomBeaconService = "0xDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD"

# Keep network configuration.
[LibP2P]
  Peers = ["/ip4/127.0.0.1/tcp/3919/ipfs/njOXcNpVTweO3fmX72OTgDX9lfb1AYiiq4BN6Da1tFy9nT3sRT2h1", "/dns4/some-keep-host.com/tcp/3919/ipfs/njOXcNpVTweO3fmX72OTgDX9lfb1AYiiq4BN6Da1tFy9nT3sRT2h1"]
  Port  = 3920
  # Override the node's default addresses announced in the network
  AnnouncedAddresses = ["/dns4/example.com/tcp/3919", "/ip4/80.70.60.50/tcp/3919"]

# Storage is encrypted
[Storage]
  DataDir = "/my/secure/location"

2.2.2. Parameters

ethereum Description Default Required

URL

The Ethereum host your keep-client will connect to. Websocket protocol/port.

""

Yes

URLRPC

The Ethereum host your keep-client will connect to. RPC protocol/port.

""

Yes

ethereum.account Description Default Required

Address

The Keep operator Ethereum account address.

""

Yes

KeyFile

The local filesystem path to your Keep operator Ethereum account keyfile.

""

Yes

ethereum.ContractAddresses Description Default Required

KeepRandomBeaconOperator

Hex-encoded address of the KeepRandomBeaconOperator Contract.

""

Yes

KeepRandomBeaconService

Hex-encoded address of the KeepRandomBeaconService Contract.

""

Yes

TokenStaking

Hex-encoded address of the TokenStaking Contract.

""

Yes

LibP2P Description Default Required

Peers

Comma separated list of network peers to boostrap against.

[""]

Yes

Port

The port to run your instance of Keep on.

3919

Yes

AnnouncedAddresses

Multiaddr formatted hostnames or addresses annouced to the Keep Network. More on multiaddr format in the libp2p reference.

[""]

No

Storage Description Default Required

DataDir

Location to store the Keep nodes group membership details.

""

Yes

3. Build from Source

See the building section in our developer docs.

4. Docker

4.1. Get Image

Latest: docker pull keepnetwork/keep-client

Tag: docker pull keepnetwork/keep-client:<tag-version>

4.2. Run Image

This is a sample run command for illustration purposes only.

export KEEP_CLIENT_ETHEREUM_PASSWORD=$(cat .secrets/eth-account-password.txt)
export KEEP_CLIENT_CONFIG_DIR=$(pwd)/config
export KEEP_CLIENT_PERSISTENCE_DIR=$(pwd)/persistence

docker run -d \
--entrypoint /usr/local/bin/keep-client
--volume $KEEP_CLIENT_PERSISTENCE_DIR:/mnt/keep-client/persistence \
--volume $KEEP_CLIENT_CONFIG_DIR:/mnt/keep-client/config \
--env KEEP_ETHEREUM_PASSWORD=$KEEP_CLIENT_ETHEREUM_PASSWORD \
--env LOG_LEVEL=debug \
-p 3919:3919 \
keepnetwork/keep-client:<version> --config /mnt/keep-client/config/keep-client-config.toml start

5. Deployment Considerations

5.1. Kubernetes

At Keep we run on GCP + Kube. To accommodate the aforementioned system considerations we use the following pattern for each of our environments:

  • Regional Kube cluster.

  • 5 beacon clients, each running minimum stake required by the network.

  • A LoadBalancer Service for each client.

  • A StatefulSet for each client.

You can see our Ropsten Kube configurations here

6. Logging

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

6.1. Configurable Values

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

6.2. Startup

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

Trust math, not hardware.

-----------------------------------------------------------------------------------------------
| Keep Random Beacon Node                                                                     |
|                                                                                             |
| Port: 3919                                                                                  |
| IPs : /ip4/127.0.0.1/tcp/3919/ipfs/16Uiu2HAmCcfVpHwfBKNFbQuhvGuFXHVLQ65gB4sJm7HyrcZuLttH    |
|       /ip4/10.102.0.112/tcp/3919/ipfs/16Uiu2HAmCcfVpHwfBKNFbQuhvGuFXHVLQ65gB4sJm7HyrcZuLttH |
-----------------------------------------------------------------------------------------------

Bonus: 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.

6.3. Peer Connections

21:19:47.129 DEBUG keep-net-w: connected to [1] peers:[16Uiu2HAm3eJtyFKAttzJ85NLMromHuRg4yyum3CREMf6CHBBV6KY]

7. ETH Networks

7.1. Mainnet

7.1.1. Boostrap Peers

"/ip4/54.39.179.73/tcp/3919/ipfs/16Uiu2HAkyYtzNoWuF3ULaA7RMfVAxvfQQ9YRvRT3TK4tXmuZtaWi",
"/ip4/54.39.186.166/tcp/3919/ipfs/16Uiu2HAkzD5n4mtTSddzqVY3wPJZmtvWjARTSpr4JbDX9n9PDJRh",
"/ip4/54.39.179.134/tcp/3919/ipfs/16Uiu2HAkuxCuWA4zXnsj9R6A3b3a1TKUjQvBpAEaJ98KGdGue67p",
"/dns4/bst-a01.core.keep.boar.network/tcp/3001/ipfs/16Uiu2HAkzYFHsqbwt64ZztWWK1hyeLntRNqWMYFiZjaKu1PZgikN",
"/dns4/bst-b01.core.keep.boar.network/tcp/3001/ipfs/16Uiu2HAkxLttmh3G8LYzAy1V1g1b3kdukzYskjpvv5DihY4wvx7D",
"/dns4/keep-boot-validator-0.prod-us-west-2.staked.cloud/tcp/3919/ipfs/16Uiu2HAmDnq9qZJH9zJJ3TR4pX1BkYHWtR2rVww24ttxQTiKhsaJ",
"/dns4/keep-boot-validator-1.prod-us-west-2.staked.cloud/tcp/3919/ipfs/16Uiu2HAmHbbMTDDsT2f6z8zMgDtJkTUDJQSYsQYUpaJjdMjiYNEf",
"/dns4/keep-boot-validator-2.prod-us-west-2.staked.cloud/tcp/3919/ipfs/16Uiu2HAmBXoNLLMYU9EcKYH6JN5tA498sXQHFWk4heK22RfXD7wC",
"/dns4/4d00662f-e56d-404a-803a-cac01ada3e15.keep.bison.run/tcp/3919/ipfs/16Uiu2HAmV3HqJjcbKMxHnDxDx4m2iEYynyYdsvU3VwaeE6Zra2P9",
"/dns4/ec1eb390-124c-4b1b-bcf7-c21709baf2b2.keep.herd.run/tcp/3919/ipfs/16Uiu2HAmVo51PqEZLADehZEbZnrp5A7qjRWFLj9E7DfwZKVhERFt",
"/dns4/2aa9b786-7360-4c22-ae73-bd95af9c11c5.keep.bison.run/tcp/3919/ipfs/16Uiu2HAm9g3QrQzSvJ8FAhgB1PmjMNgjPd3pDaJJqsdSisGsnaFe"

7.1.2. Contracts

Contract addresses needed to boot the Random Beacon client:

Token

TokenStaking

0x6D1140a8c8e6Fac242652F0a5A8171b898c67600

RandomBeacon

KeepRandomBeaconService

0x17056632d8db5a5c42fdE25132C59DD975a6da7F

KeepRandomBeaconOperator

0x70F2202D85a4F0Cad36e978976f84E982920A624

7.2. Testnet

Keep uses the Ethereum Ropsten Testnet.

7.2.1. Faucet

The KEEP faucet will will issue a 300k KEEP token grant for the provided Ethereum account. You can use the faucet from your web browser or via a terminal using curl.

To use the faucet you need to pass your Ethereum account to the faucet endpoint with the parameter ?account=<eth-account-address>.

Curl Example:

curl 'https://us-central1-keep-test-f3e0.cloudfunctions.net/keep-faucet-ropsten?account=0x0eC14BC7cCA82c942Cf276F6BbD0413216dDB2bE'

Browser Example:

https://us-central1-keep-test-f3e0.cloudfunctions.net/keep-faucet-ropsten?account=0x0eC14BC7cCA82c942Cf276F6BbD0413216dDB2bE

Once you’ve got your KEEP token grant you can manage it with our token dashboard.

7.2.2. Bootstrap Peers

"/dns4/bootstrap-0.test.keep.network/tcp/3919/ipfs/16Uiu2HAmCcfVpHwfBKNFbQuhvGuFXHVLQ65gB4sJm7HyrcZuLttH",
"/dns4/bootstrap-1.test.keep.network/tcp/3919/ipfs/16Uiu2HAm3eJtyFKAttzJ85NLMromHuRg4yyum3CREMf6CHBBV6KY",
"/dns4/bootstrap-2.test.keep.network/tcp/3919/ipfs/16Uiu2HAmNNuCp45z5bgB8KiTHv1vHTNAVbBgxxtTFGAndageo9Dp",
"/dns4/bootstrap-3.test.keep.network/tcp/3919/ipfs/16Uiu2HAm8KJX32kr3eYUhDuzwTucSfAfspnjnXNf9veVhB12t6Vf",
"/dns4/bootstrap-4.test.keep.network/tcp/3919/ipfs/16Uiu2HAkxRTeySEWZfW9C83GPFpQUXvrygmZryCN6DL4piZrbAv4",
"/dns4/bootstrap-1.core.keep.test.boar.network/tcp/3001/ipfs/16Uiu2HAkuTUKNh6HkfvWBEkftZbqZHPHi3Kak5ZUygAxvsdQ2UgG",
"/dns4/bootstrap-2.core.keep.test.boar.network/tcp/3001/ipfs/16Uiu2HAmQirGruZBvtbLHr5SDebsYGcq6Djw7ijF3gnkqsdQs3wK"

7.2.3. Contracts

Contract addresses needed to boot the Random Beacon client:

Token

TokenStaking

0xEb2bA3f065081B6459A6784ba8b34A1DfeCc183A

RandomBeacon

KeepRandomBeaconService

0xF9AEdd99357514d9D1AE389A65a4bd270cBCb56c

KeepRandomBeaconOperator

0x440626169759ad6598cd53558F0982b84A28Ad7a

8. Staking

8.1. Terminology

address

Hexadecimal string consisting of 40 characters prefixed with "0x" uniquely identifying Ethereum account; derived from ECDSA public key of the party. Example address: 0xb2560a01e4b8b5cb0ac549fa39c7ae255d80e943.

owner

The address owning KEEP tokens or KEEP token grant. The owner’s participation is not required in the day-to-day operations on the stake, so cold storage can be accommodated to the maximum extent.

operator

The address of a party authorized to operate in the network on behalf of a given owner. The operator handles the everyday operations on the delegated stake without actually owning the staked tokens. An operator can not simply transfer away delegated tokens, however, it should be noted that operator’s misbehaviour may result in slashing tokens and thus the entire staked amount is indeed at stake.

beneficiary

the address where the rewards for participation and all reimbursements are sent, earned by an operator, on behalf of an owner

delegated stake

an owner’s staked tokens, delegated to the operator by the owner. Delegation enables KEEP owners to have their wallets offline and their stake operated by operators on their behalf.

operator contract

Ethereum smart contract handling operations that may have an impact on staked tokens.

authorizer

the address appointed by owner to authorize operator contract on behalf of the owner. Operator contract must be pre-approved by authorizer before the operator is eligible to use it and join the specific part of the network.

8.2. Delegating tokens

KEEP tokens are delegated by the owner. During the delegation, the owner needs to appoint an operator, beneficiary, and authorizer. Owner may delegate owned tokens or tokens from a grant. Owner may decide to delegate just a portion of owned tokens or just a part of tokens from a grant. Owner may delegate multiple times to different operators. Tokens can be delegated using Tokens page in KEEP token dashboard and a certain minimum stake defined by the system is required to be provided in the delegation. The more stake is delegated, the higher chance to be selected to relay group.

Delegation takes immediate effect but can be cancelled within one week without additional delay. After one week operator appointed during the delegation becomes eligible for work selection.

8.3. Authorizations

Before operator is considered as eligible for work selection, authorizer appointed during the delegation needs to review and authorize Keep Random Beacon smart contract. Smart contracts can be authorized using KEEP token dashboard. Authorized operator contracts may slash or seize tokens in case of operator’s misbehavior.