Installing and running The Eye of Satoshi

6 min readSep 30, 2020

In this short post I am going to walk you trough how to install and run an instance of The Eye of Satoshi (TEOS) as of version 0.1.1.

I will be using an Ubuntu 20.04 docker image, but the installation steps would be similar for other UNIX versions or even for OSX (it may mainly differ on how to satisfy initial dependencies).

Satisfying OS dependencies

The first thing we need to do once we logged into our system is to satisfy the system dependencies. They can be found in the DEPENDENCIES.

Mainly we need:

openssl version 1.1+ (which is most likely satisfied already).
python version 3.7+ and pip for the corresponding python version.
bitcoind

There are other dependencies that are also required, but that your OS may already satisfy. For instance, libffi-dev or libleveldb-dev. We will add them just in case.

We will start by the ones that can be satisfied via the package manager and add some additional tools that will come up handy:

sudo apt-get update && sudo apt-get install -y python3 python3-dev python3-pip libffi-dev libleveldb-dev wget git vim

Make sure you installed a python version ≥ 3.7. It may not be the case if you already had an old version of python3 installed in your system:

python3 --version

Checking python3 version

Installing Bitcoin

Now that most of the dependencies are satisfied it is time to download Bitcoin and TEOS. For Bitcoin we can get a pre-compiled copy from bitcoin.org or compile from source. We will go with the former for the tutorial to keep it simple, but feel free to pick whatever option suits you best.

Go to https://bitcoin.org/en/download and get the link from the latest Bitcoin release:

Then move to your home folder and use wget to download it (it may take a while depending on your bandwidth):

cd 
wget https://bitcoin.org/bin/bitcoin-core-0.20.1/bitcoin-0.20.1-x86_64-linux-gnu.tar.gz

Since we are not compiling from source, it is highly recommended that you verify the dowloaded software. You can check https://bitcoincore.org/en/download/#verify-your-download for guidelines on how to do it depending on your OS.

Once we have verified the file we need to uncompress it, that’s:

tar -xvf bitcoin-0.20.1-x86_64-linux-gnu.tar.gz

And we will also create symbolic links to bitcoind and bitcoin-cli so we can use the commands from the command line:

ln -s ~/bitcoin-0.20.1/bin/bitcoind /usr/bin/
ln -s ~/bitcoin-0.20.1/bin/bitcoin-cli /usr/bin/

Finally, check that the links were properly created by running bitcoind -h and bitcoin-cli -h.

Installing The Eye of Satoshi

To install TEOS we need to get the code from the repository. That’s:

git clone https://github.com/talaia-labs/python-teos.git

That will create a folder called python-teos in our current folder. Now we will move to the code folder and checkout to the proper branch. We will be using v0.1.1.

cd python-teos && git checkout v0.1.1

Now that we have the right version of the code we can install it.

Install as root

If you’d like to install TEOS as a system package for all users, you can simply run:

sudo pip install .

That will install all the required python dependencies in you system alongside teosd(the tower daemon) and teos-cli (a command line interface to interact with the tower). You can also add a developer flag to the installation if you wish to install teos-client, a testing and development client.

DEV=1 sudo pip install .

Install as user

If you’d rather not use sudo to install TEOS, you can do it as a user running:

pip install .

That will install the binaries at ~/.local/bin, so you need to make sure that’s part of your $PATH. If it is not, you’ll get a warning during the installation similar to:

You can fix this by running:

export PATH=$PATH:~/.local/bin/
echo export PATH=$PATH:~/.local/bin/ >> ~/.bashrc

Check that the installation succeeded

Finally, to check that the installation was successful you can run teosd -h and teos-cli -h (and alternatively teos-client -h if you installed with development flags).

Running Bitcoin

In order to run your TEOS instance you first need a running Bitcoin node. Since for the tutorial we have just downloaded ours, we will run one on regtest, but followup tutorials will guide you trough how to operate the tower on mainnet.

In order for the tower to work, we need to enable the RPC and ZMQ interfaces for Bitcoin, as well as transaction indexing. Here’s the bitcoin.conf we will be using:

# [network]
dnsseed=0# [debug]
daemon=1
regtest=1
debug=1# [rpc]
server=1
rpcuser=user
rpcpassword=passwd# [blockchain]
txindex=1# [zmq]
zmqpubhashblock=tcp://127.0.0.1:28332
zmqpubrawblock=tcp://127.0.0.1:28332
zmqpubhashtx=tcp://127.0.0.1:28333
zmqpubrawtx=tcp://127.0.0.1:28333

Notice that, while this is OK for our tutorial, it is highly insecure for a production environment. Pick a better rpcuser:rpcpassword pair for production.

Copy it to your bitcoin data folder (usually ~/.bitcoin/bitcoin.conf). You may need to create the folder if you have not started your node before.

Now it’s time to start the node (we’ll do it in daemon mode):

bitcoind

You can check that Bitcoin is properly running with bitcoin-cli -getinfo :

That should return that the chain is regtest.

Running TEOS

Now that our Bitcoin node is running we can start our tower. By default TEOS runs on mainnet, so we will need to start it on regtest. If TEOS does not find a Bitcoin node running in the same network it is trying to run, it will refuse to run:

teosd --btcnetwork=regtest

This will run the tower and tell you about its identifier (tower_id) and the endpoints of the running interfaces.

Notice that, by default, TEOS will try to connect to the RPC and ZMQ servers matching the example bitcoin.conf file provided. It will also try to use the insecure rpcuser:rpcpassword pair, so if you have changed any of the settings you will need to tell TEOS about it. You can do so using the command line parameters or by creating a configuration file in the TEOS datadir (~/.teos/teos.conf).

Command line parameters can be checked by running with -h:

teosd -h

If you have changed the rpcuser:rpcpassword pair you will need to add to the call--btcrpcuser=your_rpc_user and --btcrpcpassword=your_password:

teosd --btcnetwork=regtest --btcrpcuser=satoshi --btcrpcpassword=notcsw

Here’s also a teos.conf sample with some of the configuration parameters (for regtest).

[bitcoind]
btc_rpc_user = user
btc_rpc_password = passwd
btc_rpc_connect = localhost
btc_network = regtest
btc_rpc_port = 18443[teos]
max_appointments = 100000

Checking the chain monitor

To conclude, we will check that the tower is keeping track of the received blocks. Since we are running on regtest we can generate a block ourselves. Open a new terminal an run:

bitcoin-cli generatetoaddress 1 $(bitcoin-cli getnewaddress)

Our tower should have detected the block straight-away

That concludes the tutorial. In the following days we will also publish some other write-ups about how to manage and interact with the tower both using the development client (teos-client) and the c-lightning plugin.