Setup and usage

Search…

Setup and usage

Here are the nuts and bolts for using the CLI

Get the CLI
The CLI support only linux and is provided as a pre-built binary with every release and also as a docker image.
​Github releases​
​https://hub.docker.com/u/tellor​
Config files.
.env - keeps private information(private keys, api keys etc.). Most commands require some secrets and these are kept in this file as a precaution against accidental exposure. For a working setup it is required to at least add one private key in your "ETH_PRIVATE_KEYS" environment variable. Multiple private keys are supported separated by ,.
index.json - all api endpoint for data providers. The cli uses these provider endpoints to gather data which is then used to submit to the onchain oracle.
manualdata.json - for providing data manually. There is currently one data point which must be manually created. The rolling 3 month average of the US PCE . It is updated monthly. Make sure to keep this file up to date.
For testing purposes, or if you want to hardcode in a specific value, you can use the file to add manual data for a given requestID. Add the request ID, a given value (with granularity), and a date on which the manual data expires.
The following example shows request ID 4, inputting a value of 9000 with 6 digits granularity. Note the date is a unix timestamp.
1
"4":{
2
 "VALUE":9000.123456,
3
 "DATE":1596153600
4
}
Copied!
config.json - optional config file to override any of the defaults. See the configuration page for full reference.
by default the cli looks for these in the ./configs folder relative to the cli folder.
Here is a quick reference how to run the cli with the default configs.
1
mkdir ./configs
2
cd ./configs
3
wget https://raw.githubusercontent.com/tellor-io/telliot/master/configs/index.json
4
wget https://raw.githubusercontent.com/tellor-io/telliot/master/configs/manualData.json
5
wget https://raw.githubusercontent.com/tellor-io/telliot/master/configs/.env.example
6
mv .env.example .env
7
cd ../
8
wget https://github.com/tellor-io/telliot/releases/latest/download/telliot
9
chmod +x telliot
Copied!
Deposit or withdraw a stake
As of now, mining requires you to deposit 500 TRB to be allowed to submit values to the oracle and earn rewards. This is a security deposit. If you are a malicious actor (aka submit a bad value), the community can vote to slash your 500 tokens. Your stake is locked for a minimum of 7 days after you run the command to request withdrawal.
Run the following command to deposit your stake:
1
./telliot stake deposit
Copied!
To unstake your tokens, you need to request a withdraw:
1
./telliot stake request
Copied!
One week after the request, the tokens are free to move at your discretion after running the command:
1
./telliot stake withdraw
Copied!
Start mining.
The same instance can be used with multiple private keys in the .env file separated by a comma.
1
./telliot mine
Copied!
Telliot supports submiting data to different contracts and the config folder contains examples for that. For example:
1
./telliot mine --config=configs/configTellorMesosphere.json
Copied!
DataServer - a shared data API feeds.
Advanced usage! If you are setting up a Tellor miner for the first time, it might be a good idea to skip this section and come back after you're up and running with one miner. See the configuration page for the required configs.
Some oracle feeds require 24h avarages and for these enough historical data is needed. Running a dataserver is the solution to always have enough historical data to generate these averages.
The network topology of this setup looks like the diagram below. One ore more miners are connected to the same data server for fetching current or historical data to submit to the oracle. The data server pulls data from the API providers, the 5 staked miners pull data from the data server and submit on-chain to the Tellor Core smart contracts.
1
                            /(0xE037)\
2
                Miner      | (0xcdd8) |
3
Tellor     <-> (multiple   | (0xb9dD) | <-> Data Server <-> Data APIs
4
(on chain)      keys)      | (0x2305) |
5
                            \(0x3233)/
Copied!
Run with Docker - https://hub.docker.com/u/tellor​
1
cp configs/.env.example configs/.env # Edit the file after the copy.
2
docker run -v $(pwd)/configs:/configs tellor/telliot:master mine
Copied!
Run cli in mining mode with k8s
tested with google cloud, but should work with any k8s cluster.
Install gcloud​
Install kubectl​
Create a k8s cluster with a single node
Login to the cluster
1
gcloud auth login --project projectName
2
gcloud container clusters get-credentials main --zone europe-west2-a --project projectName
Copied!
Deploy the cli (by default deployed to run as a miner)
1
git clone https://github.com/tellor-io/telliot
2
cd telliot
3
export INSTANCE_NAME=lat # Use max 3 characters due to k8s limitation for port names.
4
export DEPL_NAME=telliot-m # This is the name of the deployment file.
5
export CFG_FOLDER=.local/configs/$DEPL_NAME-$INSTANCE_NAME # Configs will be copied to this folder.
6
export DEPL_INSTANCE_NAME=$DEPL_NAME-$INSTANCE_NAME
7
mkdir -p $CFG_FOLDER
8
​
9
# Create the secret file.
10
cp configs/.env.example $CFG_FOLDER/.env # Edit the file after the copy.
11
​
12
touch $CFG_FOLDER/config.json # Create an empty file and if needed overwrite the defaults.
13
​
14
# Copy the manual data file.
15
cp configs/manualData.json $CFG_FOLDER/manualData.json
16
​
17
# Apply the configs.
18
kubectl create secret generic $DEPL_INSTANCE_NAME --from-env-file=$CFG_FOLDER/.env
19
kubectl create configmap $DEPL_INSTANCE_NAME \
20
  --from-file=configs/index.json \
21
  --from-file=$CFG_FOLDER/config.json \
22
  --from-file=$CFG_FOLDER/manualData.json \
23
  -o yaml --dry-run=client | kubectl apply -f -
24
​
25
# Copy the manifest and run it.
26
cp configs/manifests/$DEPL_NAME.yml $CFG_FOLDER/$DEPL_NAME.yml
27
sed -i "s/$DEPL_NAME/$DEPL_INSTANCE_NAME/g" $CFG_FOLDER/$DEPL_NAME.yml
28
kubectl apply -f $CFG_FOLDER/$DEPL_NAME.yml
Copied!
Run the cli in dataserver mode.
1
export INSTANCE_NAME=lat # Use max 3 characters due to k8s limitation for port names.
2
export CFG_FOLDER=.local/configs/db
3
export DEPL_NAME=telliot-db
4
mkdir -p $CFG_FOLDER
5
​
6
# Run the same commands as the mining deployment.
7
​
8
See [configuration page](configuration.md) on how to setup other instances to connect to this remote dataserver
9
​
10
### To run another instance.
11
​
12
```bash
13
export NAME= # Put an instance name here. Something short as some properties are limited by length(e.g `export NAME=PR1`).
14
# Run all the other commands from initial k8s setup.
Copied!
To delete an instance.
1
kubectl delete statefulsets.apps $DEPL_INSTANCE_NAME
2
kubectl delete service $DEPL_INSTANCE_NAME
3
kubectl delete configmap $DEPL_INSTANCE_NAME
4
kubectl delete secret $DEPL_INSTANCE_NAME
5
kubectl delete persistentvolumeclaims $DEPL_INSTANCE_NAME
Copied!
To run a custom docker image.
1
export REPO= # Your docker repository name.
2
docker build . -t $REPO/telliot:custom
3
docker push $REPO/telliot:latest
4
​
5
sed -i "s/tellor\/telliot:latest/$REPO\/telliot:custom/g" $CFG_FOLDER/telliot-m.yml
6
kubectl apply -f $CFG_FOLDER/telliot-m.yml
Copied!
Optionally deploy the monitoring stack with Prometheus and Grafana.
1
kubectl apply -f configs/manifests/monitoring-persist.yml
2
kubectl apply -f configs/manifests/monitoring.yml
Copied!
Optionally deploy the alerting manager and get alerts on your Telegram bot.
This uses the alertmanager bot. see here for more info and available commands.
1
# Create a secret for the telegram authentication.
2
kubectl create secret generic alertmanager-bot \
3
  --from-literal=admin='<telegram admin>' \
4
  --from-literal=token='<telegram token>'
5
kubectl apply -f configs/manifests/alerting-persist.yml
6
kubectl apply -f configs/manifests/alerting.yml
Copied!