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.
-
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.
-
A way to monitor your operator wallet balance, node connectivity, underlying system health, and logs. A good option is Keep Network Monitoring System from Boar Network.
-
Each Keep ECDSA client running on the network requires a unique Ethereum operator account.
-
Each Keep ECDSA 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:
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 ECDSA client.
| 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 |
Keep ECDSA smart contracts do not reimburse the operator for submitted transactions. It is the responsibility of the application using ECDSA keeps to make sure operators are rewarded accordingly and the outcomes are net-positive. It is expected that the operators have enough ETH on the accounts used by clients to submit the required transactions and that the operator account balance is monitored and refilled as needed. Bear in mind that the higher stake is and the higher unbonded value is, the operator is selected more frequently and is expected to submit more transactions as a result.
Below is the average gas cost of the most important transactions the client is submitting:
| TX | Gas Cost | Reimbursed |
|---|---|---|
Submit keep public key |
150 000 |
No |
Submit keep signature |
30 500 |
No |
Update operator status in sortition pool |
125 000 |
No |
For example, if we expect the operator to handle a keep by submitting all the transactions mentioned
above for each keep, the operator needs to have (150 000 + 30 500 + 125 000) * gas_price ETH on
the account:
-
For the gas price of 20 Gwei, this is at least 0.00611 ETH.
-
For the gas price of 100 Gwei, this is at least 0.03055 ETH.
-
For the gas price of 800 Gwei, this is at least 0.2444 ETH.
It is paramount that the operators have some safety margin and consider the current gas price, stake, and unbonded value when funding their accounts.
It is highly recommended to keep your operator account above 1 eth (and monitor it continuously) to be safe from surges in transactions.
Default port mappings.
| Egress | Port |
|---|---|
Ethereum Network |
TCP: |
Keep Network |
TCP: |
| Ingress | Port |
|---|---|
Keep Network |
|
If you set a different port in your keep-ecdsa configuration, or configure peers with
non-default ports configured, firewall rules will need to be adjusted accordingly.
Application configurations are stored in a .toml file and passed to the application run command
with the --config flag. Example:
./keep-ecdsa --config /path/to/your/config.toml start| Property | Description | Default | Required |
|---|---|---|---|
|
|||
|
The Ethereum host your keep-ecdsa will connect to. Websocket protocol/port. |
|
Yes |
|
The Ethereum host your keep-ecdsa will connect to. RPC protocol/port. |
|
Yes |
|
|||
|
The local filesystem path to your Keep operator Ethereum account keyfile. |
|
Yes |
|
|||
|
Hex-encoded address of the BondedECDSAKeepFactory Contract. |
|
Yes |
|
Hex-encoded address of the TBTCSystem Contract. |
|
Yes, if operating for tBTC v1 |
|
|||
|
Location to store the Keep nodes group membership details. |
|
Yes |
|
|||
|
Comma separated list of network peers to bootstrap against. See list of bootstrap peers. |
|
Yes |
|
The port to run your instance of Keep on. |
|
Yes |
|
Multiaddr formatted hostnames or addresses announced to the Keep Network. More on multiaddr format in the libp2p reference. |
|
No |
|
|||
|
Timeout for TSS protocol pre-parameters generation. |
|
No |
|
|||
|
The amount of time your client will try to communicate with the other signers to recover the underlying bitcoin from a deposit after it has been liquidated. |
|
No |
|
|||
|
The btc address or *pub (xpub, ypub, zpub) that you would like recovered btc funds to be sent too, see examples. |
|
Yes |
|
The maximum fee per vbyte that you’re willing to pay in order to claim your share of the underlying btc after a liquidation. |
|
No |
|
The bitcoin chain that you want to connect to. Allowed Values: ["mainnet", "regtest", "simnet", "testnet3"] |
|
No |
|
An endpoint pointing to a running electrs service. |
|
No |
The following entries are examples of
Extensions.TBTC.Bitcoin.BeneficiaryAddress configurations. For example, to
configure the beneficiary address as a mainnet xpub extended public key, the
configuration would be:
[Extensions.TBTC.Bitcoin]
BeneficiaryAddress = "xpub6Cg41S21V____REPLACE_WITH_VALID_DATA____qLdk9dxyXQUoy7ALWQFNn5K1me74aEMtS6pUgNDuCYTTMsJzCAk9sk1"Supported Beneficiary Address formats with examples:
| Description | Sample Value |
|---|---|
mainnet |
|
xpub extended public key |
|
ypub extended public key |
|
zpub extended public key |
|
P2PKH btc address |
|
P2SH btc address |
|
Bech32 (segwit) P2WPKH btc address |
|
Bech32 (segwit) P2WPSH btc address |
|
P2PK compressed btc public key ( |
|
P2PK compressed btc public key ( |
|
P2PK compressed btc public key ( |
|
testnet3/regtest |
|
tpub extended public key |
|
upub extended public key |
|
vpub extended public key |
|
P2PKH btc address |
|
P2SH btc address |
|
Bech32 (segwit) P2WPKH btc address |
|
See the building section in our developer docs.
Latest:
docker pull keepnetwork/keep-ecdsa-client
Tag:
docker pull keepnetwork/keep-ecdsa-client:<tag-version>
This is a sample run command for illustration purposes only.
export KEEP_ECDSA_ETHEREUM_PASSWORD=$(cat .secrets/eth-account-password.txt)
export KEEP_ECDSA_CONFIG_DIR=$(pwd)/config
export KEEP_ECDSA_PERSISTENCE_DIR=$(pwd)/persistence
docker run -d \
--entrypoint /usr/local/bin/keep-ecdsa \
--volume $KEEP_ECDSA_PERSISTENCE_DIR:/mnt/keep-ecdsa/persistence \
--volume $KEEP_ECDSA_CONFIG_DIR:/mnt/keep-ecdsa/config \
--env KEEP_ETHEREUM_PASSWORD=$KEEP_ECDSA_ETHEREUM_PASSWORD \
--env LOG_LEVEL=debug \
--log-opt max-size=100m \
--log-opt max-file=3 \
-p 3919:3919 \
keepnetwork/keep-ecdsa-client:<version> --config /mnt/keep-ecdsa/config/keep-ecdsa-config.toml startBelow are some of the key things to look out for to make sure you’re booted and connected to the network:
LOG_LEVEL=DEBUG
IPFS_LOGGING_FMT=nocolor
GOLOG_FILE=/var/log/keep/keep.log
GOLOG_TRACING_FILE=/var/log/keep/trace.json▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄
▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓ ▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓ ▐▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓
▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▄▄▄▄ ▓▓▓▓▓▓▄▄▄▄ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓▀▀▀▀ ▓▓▓▓▓▓▀▀▀▀ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀
▓▓▓▓▓▓ ▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌
▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓
Trust math, not hardware.
-----------------------------------------------------------------------------------------------
| Keep ECDSA Node |
| |
| Port: 3919 |
| IPs : /ip4/127.0.0.1/tcp/3919/ipfs/16Uiu2HAmCcfVpHwfBKNFbQuhvGuFXHVLQ65gB4sJm7HyrcZuLttH |
| /ip4/10.102.0.112/tcp/3919/ipfs/16Uiu2HAmCcfVpHwfBKNFbQuhvGuFXHVLQ65gB4sJm7HyrcZuLttH |
-----------------------------------------------------------------------------------------------If you want to share your LibP2P address with others you can get it
from the startup log. This can be helpful for debugging issues where a peer ID
is needed. Additionally, if you’re running multiple nodes, you may want to add
your own nodes to the bootstrap list configured in LibP2P.Peers alongside
the official bootstrap nodes.
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.
Example:
/ip4/127.0.0.1/tcp/3919/ipfs/16Uiu2HAmCcfVpHwfBKNFbQuhvGuFXHVLQ65gB4sJm7HyrcZuLttH
becomes
/ip4/99.153.149.50/tcp/3919/ipfs/16Uiu2HAmCcfVpHwfBKNFbQuhvGuFXHVLQ65gB4sJm7HyrcZuLttH.
[LibP2P]
Peers = [
"/dns4/bst-a01.ecdsa.keep.boar.network/tcp/4001/ipfs/16Uiu2HAkzYFHsqbwt64ZztWWK1hyeLntRNqWMYFiZjaKu1PZgikN",
"/dns4/bst-b01.ecdsa.keep.boar.network/tcp/4001/ipfs/16Uiu2HAkxLttmh3G8LYzAy1V1g1b3kdukzYskjpvv5DihY4wvx7D",
"/dns4/keep-boot-validator-0.prod-us-west-2.staked.cloud/tcp/3920/ipfs/16Uiu2HAmDnq9qZJH9zJJ3TR4pX1BkYHWtR2rVww24ttxQTiKhsaJ",
"/dns4/keep-boot-validator-1.prod-us-west-2.staked.cloud/tcp/3920/ipfs/16Uiu2HAmHbbMTDDsT2f6z8zMgDtJkTUDJQSYsQYUpaJjdMjiYNEf",
"/dns4/keep-boot-validator-2.prod-us-west-2.staked.cloud/tcp/3920/ipfs/16Uiu2HAmBXoNLLMYU9EcKYH6JN5tA498sXQHFWk4heK22RfXD7wC",
"/ip4/54.39.179.73/tcp/4001/ipfs/16Uiu2HAkyYtzNoWuF3ULaA7RMfVAxvfQQ9YRvRT3TK4tXmuZtaWi",
"/ip4/54.39.186.166/tcp/4001/ipfs/16Uiu2HAkzD5n4mtTSddzqVY3wPJZmtvWjARTSpr4JbDX9n9PDJRh",
"/ip4/54.39.179.134/tcp/4001/ipfs/16Uiu2HAkuxCuWA4zXnsj9R6A3b3a1TKUjQvBpAEaJ98KGdGue67p",
"/dns4/r-4d00662f-e56d-404a-803a-cac01ada3e15-keep-ecdsa-0.4d00662f-e56d-404a-803a-cac01ada3e15.keep.bison.run/tcp/3919/ipfs/16Uiu2HAmV3HqJjcbKMxHnDxDx4m2iEYynyYdsvU3VwaeE6Zra2P9",
"/dns4/r-ec1eb390-124c-4b1b-bcf7-c21709baf2b2-keep-ecdsa-0.ec1eb390-124c-4b1b-bcf7-c21709baf2b2.keep.herd.run/tcp/3919/ipfs/16Uiu2HAmVo51PqEZLADehZEbZnrp5A7qjRWFLj9E7DfwZKVhERFt",
"/dns4/r-2aa9b786-7360-4c22-ae73-bd95af9c11c5-keep-ecdsa-0.2aa9b786-7360-4c22-ae73-bd95af9c11c5.keep.bison.run/tcp/3919/ipfs/16Uiu2HAm9g3QrQzSvJ8FAhgB1PmjMNgjPd3pDaJJqsdSisGsnaFe"
]Contract addresses needed to boot a Keep ECDSA client:
| Name | Address |
|---|---|
BondedECDSAKeepFactory |
|
TBTCSystem |
|
tBTC Sortition Pool (for authorization) |
|
When you run your ecdsa node, you can check to make sure you didn’t get any error logs and that you see a log entry that looks like:
2021-08-10T17:52:45.184Z INFO keep-ecdsa operator is registered for application [0xe20A5C79b39bC8C363f0f49ADcFa82C2a01ab64a]This indicates that you have successfully registered for the sortition pool! If you are not seeing that message, that means that either you’re not eligible, have something misconfigured, etc. To further verify, you can navigate to
and find the functions isOperatorRegistered and isOperatorEligible. Fill in your operator address for
_operator (address) and the TBTCSystem address
(0xe20A5C79b39bC8C363f0f49ADcFa82C2a01ab64a) for the application address and
run the query. If it returns true, you’re in business! If it doesn’t, it may
be time to reach out for help at our discord.
Keep uses the Ethereum Ropsten Testnet.
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=0x0eC14BC7cCA82c942Cf276F6BbD0413216dDB2bEOnce you’ve got your KEEP token grant you can manage it with our token dashboard.
Bootstrap peers will come and go on testnet. As long as at least one of your configured peers is up, there is no need to worry.
[LibP2P]
Peers = [
"/dns4/bootstrap-1.ecdsa.keep.test.boar.network/tcp/4001/ipfs/16Uiu2HAmPFXDaeGWtnzd8s39NsaQguoWtKi77834A6xwYqeicq6N",
"/dns4/ecdsa-2.test.keep.network/tcp/3919/ipfs/16Uiu2HAmNNuCp45z5bgB8KiTHv1vHTNAVbBgxxtTFGAndageo9Dp",
"/dns4/ecdsa-3.test.keep.network/tcp/3919/ipfs/16Uiu2HAm8KJX32kr3eYUhDuzwTucSfAfspnjnXNf9veVhB12t6Vf",
]Contract addresses needed to boot a Keep ECDSA client:
| Name | Address |
|---|---|
BondedECDSAKeepFactory |
|
TBTCSystem |
|
tBTC Sortition pool (for authorization) |
|
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 can be enabled in the configuration .toml file. It is possible to customize 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 1623235129789The 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 can be enabled in the configuration .toml file. It is possible to customize port at which
diagnostics endpoint is exposed.
Example diagnostics endpoint call result:
$ curl localhost:9501/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"},
...
]
}- 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.
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 12 hours without additional delay. After 12 hours operator appointed during the delegation becomes eligible for work selection.
Before operator is considered as eligible for work selection, the authorizer appointed during the delegation needs to review and perform the following authorizations:
- BondedECDSAKeepFactory operator contract
-
Allows the factory to slash tokens on misbehaviour and makes the operator eligible for work selection. This is an operator contract much like the
KeepRandomBeaconOperatorcontract. UsestokenStaking.authorizeOperatorContract. - Bond Access for tBTC
-
Allows for the authorized application (tBTC) to bond from the available bond value stored in the
KeepBondingcontract. UseskeepBonding.authorizeSortitionPoolContract.
These smart contracts can be authorized using the KEEP token dashboard. As always,
authorized operator contracts may slash or seize tokens in case of operator
misbehavior. Contracts authorized for bonding are set in ContractAddresses
in the config file. The operator must explicitly register as a candidate for selection,
as a safeguard against choosing clients that have not yet booted up; the sanctioned
applications list allows the client software to automatically register as a candidate
on startup.
Please refer the network troubleshooting guide.