This is a step-by-step guide for installing and using the Disputable Values Monitor (DVM). The methods outlined here were confirmed working on a fresh installation of Ubuntu 20.04 LTS (Amazon t2.small AWS instance). Individual commands may differ with other environments particularly for installing python 3.9.
Note: The Disputable Values Monitor uses Telliot as a dependency, and one important config file (endpoints.yaml) is shared. If you’re using the DVM to monitor a set of networks that’s different from the set that you report on with Telliot, we recommend using a separate machine (or instance) for the DVM.
Prerequisites:
- A computer or virtual machine running linux with python 3.9 installed as the current version. A guide for installing Python 3.9 and venv can be found here.
- Your preferred tool for operating the DVM (a python process) continuously. If you’re not sure what to use, check out my guide for using GNU screen here.
- Node endpoints for Ethereum Mainnet and any other network(s) that you want to monitor. You can use your own node, or use a provider like Infura.
- If you plan to use the DVM for automatic disputing, you will need an ethereum address (public and private keys) loaded with TRB tokens and gas (native tokens) for calling the dispute function.
- A twilio account that the DVM can use to send you text messages. Follow the steps shown here.
The Guide
This is a beginner-friendly guide. Familiarity with the command line will be helpful, but otherwise no assumptions are made about your technical skills. We will go over all the commands necessary to set up the Disputable Values Monitor to send you text alerts about questionable values and even automatically dispute bad values that are submitted to the Tellor oracle.
Download Necessary Files and Create the Python Virtual Environment
1) Clone the repo: git clone https://github.com/tellor-io/disputable-values-monitor
2) Change directory to the disputable-values-monitor folder: cd disputable-values-monitor
3) Create a python virtual environment for installation: python3 -m venv venv
4) Activate the virtual environment: source venv/bin/activate
Your terminal command prompt should now show “(venv)” on the left to indicate that you’re using a virtual environment as in the image below:
Note: If you’ve completed these steps and you’re seeing errors related to python, pip, or venv, these will need to be dealt with before you can continue. Here’s a step-by-step guide for installing python and venv.
Install and Configure the DVM
1) Install the Disputable Values Monitor with the command: pip install -e .
2) Copy the “vars.example.sh” and rename it to “vars.sh”: cp vars.example.sh vars.sh
3) Log in to twilio and navigate to the “Console” page where you can find your Account Info like in the image below:
Copy your Account SID, Auth Token, and phone number and keep these in a safe place.
4) Open vars.sh in nano (or your preferred text editor): nano vars.sh
5) Use your arrow keys to navigate the file. In between the quotes, paste in your “AUTH_TOKEN”, “TWILIO_ACCOUNT_SID”, “TWILIO_FROM” (The Twilio phone number you purchased with no special characters or spaces) and “ALERT_RECIPIENTS” (The Twilio phone number you purchased with no special characters or space.
If you want to send alerts to more than one number, separate those numbers with commas as shown below.
When you’re done editing, use ‘crtl+x’ to exit the document and choose ‘y’ to save your changes. If you make a mistake simply exit choosing ‘n’ and start over.
5) Export these environment variables with the command: source vars.sh
Next we need to set the chains you want to monitor by providing RPC (node) endpoints for those.
6) Generate telliot config files with the command telliot config init
Note: If you’ve already used telliot on your machine, config init can be skipped.
7) Change directory to the telliot folder: cd ~/telliot
8) Open endpoints.yaml in your text editor: nano endpoints.yaml
9) Use your arrow keys to navigate the file. You’ll see dashes on the left side followed by 6 lines for each network where Tellor is deployed:
The Disputable Values Monitor will listen for newReport events on every network included in the endpoints.yaml file. Carefully delete the lines for all the networks that you don’t want or need to monitor with the DVM. (Use ctrl^k to delete lines.)
For the networks that you do want to monitor, simply edit the url to match your endpoint as shown in the picture here:
You are now ready to use the DVM to receive text alerts for bad Tellor oracle data!
Start the Disputable Values Monitor!
Fire up the DVM and start monitoring data with the command: [cli -c 0.1 –wait 60].
You will be prompted on whether or not you want to run alerts only . Enter “y”.
If your screen looks like the image below, you’re successfully monitoring Tellor! If your goal is to use the DVM to receive text alerts only, you’re all done.
Note: The threshold for alerts is adjusted by changing the value of the [-c] flag. A value of 0.1 means that you want to get a text if the value is 10% different from the value calculated by the DVM. If you wanted to increase the threshold to 25%, use a value of 0.25 and so on.
Automatic Disputing
Important: Values submitted to Tellor are subject to dispute if they are incorrect. If you’re not familiar with the dispute system, please take a moment to read the DISPUTING DATA section of the Tellor documentation before you continue.
Caution: Practice running the DVM on a testnet first! This is experimental software. See here for instructions on how to get testnet TRB for initiating test disputes.
Now that that’s out of the way, let’s learn how to set it up!
Set up Automatic Disputing of Spot-Price Values and EVM Calls
First, we need to provide an Ethereum account (pk) that the DVM can use for calling functions. I’ll use polygon mumbai testnet for the example / screenshots included below.
1) Add your disputing address as a telliot account with the command: telliot accounts add ACCOUNT_NAME 0xYOUR_PRIVATE_KEY 80001
Replace “ACCOUNT_NAME” with any name you choose. Change the private key to the private key of your disputer wallet address. At the end, provide the network ID for your Tellor network (I’m using 80001 for Polygon Mumbai Testnet). After you enter the telliot account command you will be prompted to set a password.
Note: If you want to automatically dispute bad values on multiple Tellor networks, include all of those networks at the end of your command separated by a single space:
telliot account add ACCOUNT_NAME 0xYOUR_PRIVATE_KEY 80001 137 10 11155111 1Tip: Here are some other useful commands for managing telliot accounts:
telliot account findShows a list of accounts (with their public address).
telliot account delete AccountNameDeletes the keys for the account “AccountName”.
Edit Your Disputing Configuation
1) Open and edit the dispute-config.yaml file with your text editor of choice: nano disputer-config.yaml
2) Use your arrow keys to navigate the file. You will find that the DVM is pre-configured to automatically dispute two types of data: ETH/USD spot prices, and EMVCall. (see image below)
Additional Spot prices are added by carefully copying and editing the 4 lines corresponding to “query_id”, “threshold”, “type”, and “amount”. For example, if you want to automatically bad ETH/USD and STETH/USD values, add a copy of the code for ETH/USD and edit the queryId to be the STETH/USD queryId.
Tip: You can easily generate queryIDs for spot prices using the tools at https://tellor.io/queryidstation/.
Start the DVM With the -d Flag
Start the Disputable Values Monitor with the command: cli -d -a YOUR_ACCOUNT_NAME -c 0.1 --wait 60
Replace “YOUR_ACCOUNT_NAME” with your telliot account name.
Enter your password when prompted. You should see a graph with recent submissions just as before.
Bad Value Test
Note: If you want to test your DVM instance on a testnet but you’re not 100% sure how to submit the bad value, feel free to reach out to me (spuddy.eth) in the Tellor discord or @0xSpuddy on twitter/X.
This is the part where we’re going to submit a bad value on purpose to see what happens to check if the DVM is working. ETH/USD price is about 1,877.01 at the time of writing, so I will submit a value of $25,000 for ETH/USD on polygon Mumbai testnet which should trigger a text message and an automatic dispute. (See below for links to the bad value and dispute transactions)
It worked!
The 25k ETH/USD submission: https://mumbai.polygonscan.com//tx/0xb528c2d0c5310ef1bc85d6922e87b96a08758abdd479d204babed93454eb5aea
The automatic dispute: https://mumbai.polygonscan.com/tx/0xd0cb63cb6e41c62dd12ac7115d957447751a88f13ac695b0db0bc211f5d2d2f5
The time that it takes for the DVM to initiate disputes depends on your setup and the configured wait period. Successful automatic disputes in the next block are well within the capabilities of the DVM!
Thanks for reading!
Questions? Feel free to give us a shout in the Tellor Discord! You can yell at me (or thank me) directly by tagging spuddy.eth#2499 or find me on Twitter.
Have a great day 🤙
