Installing Tezos TAPS
A step by step guide to getting started
Update 2: TAPS v1.1.1 was released on September 10th 2019 and features batch payments by default, bond pool management and advanced options like a rewards “repay” button.
Update 1: TAPS v1.0.0 was released on February 28th 2019 and features a native wallet, making it independent from Tezos node. A new article will be published with screenshots.
Tezos.Rio, a team of developers, designers, investors and researchers from Rio de Janeiro, has launched in February 16th their first version of TAPS software (acronym for Tezos Automatic Paying System), a system created to allow bakers to automate their rewards distribution to their delegators. An introduction to TAPS and how it works can be found in our previous article: https://medium.com/@lmilfont/bakers-on-holiday-6b15b300f0b1
TAPS installation have some requirements to get it working. This article intends to be a step by step guide to getting started.
Installing TAPS
TAPS is written in CFML, so it needs a Coldfusion application server to run. We designed TAPS to run on Lucee, the free, open-source version of Coldfusion.
Step 1
Download Lucee Server from https://download.lucee.org/
Choose the appropriate binaries from the “Release” column. In our case, Linux 64b installer.
While we wait for the download to finish, it will be convenient to download the H2 Database Lucee extension, that is on that same web page. You can scroll down and manually look for it, or just press CTRL + F and type H2:
Click on “download version (1.3.172)” and let if finish for future use.
After Lucee server download have finished, check your download folder. You will have a file named “lucee-5.2.9.031-pl1-linux-x64-installer.run”. This is the executable binary Lucee installer.
You may have to get root privileges for the download folder. After that, click over the Lucee installer icon with the right mouse button and choose “open”. You might see the message below:
Choose “Make executable and run”. That will execute Lucee installer wizard.
Click “Forward” button. The license agreement screen will show. Select “I accept license agreement”, then click “Forward”.
Lucee installer will then ask for Installation Directory. Keep the default “/opt/lucee” and press “Forward”.
Now installer will prompt you for a password. This will be needed to access Lucee administrator configuration page. Type a password twice, with 6 characters or more. Write it down in a piece of paper, so you don’t forget it.
Lucee will need a web port to respond when requested. For now, do not change any of the default port numbers. Just press “Forward” button.
Next, also maintain the “root” user as the system user account that Tomcat will use.
Now installer will ask if we want to start Lucee automatically on every boot. Choose Yes.
The next step is very important. We don’t want to enable external access to Lucee, as we are not publishing a public web site. Our intention is restrict access to localhost only. So, here, we will leave the checkbox blank, as we will NOT install Apache Connector.
With all previous information given to Lucee wizard, it will start copying files. It will show a “Ready to Install” window. Just click “Forward” to proceed and wait it to finish:
After pressing the “Finish” button, on some systems the “Lucee Welcome Screen” might not show, even with the checkbox set to open it. Don’t worry about that.
Open a web browser and lets see the “Lucee Welcome Screen” by typing its address manually: http://127.0.0.1:8888/
If you see that screen, this means that Lucee has been successfully installed and can run CFML code on your server. Nice!
You may Start/Stop Lucee Application Server with the command:
sudo /opt/lucee/lucee_ctl [start] [stop]
Now that Lucee is successfully installed, we have to add a Database Management System to it. Our database of choice, for speed and simplicity was H2 Database. The installation is very simple.
In our download folder we might have laying the file “org.h2–1.3.172.lex”, as we have downloaded H2 in a previous step. The file extension “.lex” means “Lucee Extension” and it is a very simple way of adding extensions to Lucee. We only have to copy this file to an specific folder inside Lucee installation directory. So, right-click “org.h2–1.3.172.lex” file, choose “Copy”. Then, go to folder /opt/lucee/tomcat/lucee-server/deploy/ and paste the file there. Done!
The Lucee Server and Database part of the installation is finished. Now we are going to Clone TAPS from its GitHub repository. Open a shell command prompt.
First, we have to get into Lucee’s webapps directory. This is a special folder where Lucee server expects to find its apps. Although this step is not difficult, it may vary depending on your operating system:
Debian : /opt/lucee/tomcat/webapps
Ubuntu: /opt/lucee/tomcat/webapps/ROOT
So, according to your system, change your directory to get into Lucee’s apps folder with the CD command:
cd /opt/lucee/tomcat/webapps
Once inside webapps (or webapps/ROOT) folder, now it’s time to actually clone Taps github repository. This will create a “taps” folder inside webapps:
git clone https://github.com/TezosRio/taps.git
TAPS source-code will then be downloaded to your local server. Once done, just follow these steps below:
- Start TAPS in your browser with http://127.0.0.1:8888/taps/index.cfm
- Log in TAPS with default user/pass: admin/admin.
Now, once logged in, go to “SETUP” page and enter your Baker’s details:
Baker ID is required so TAPS will gather information about rewards and delegators of the baker from TzScan.io API.
Default rewards fee percentage will be used to populate the initial information of the charged fee for all delegators of the baker. This can be changed individually later.
Updated Frequency field is one of the most importants for TAPS. This will configure the scheduled-task (the heart of TAPS) to be run every n minutes. There is no need for specifying this lower then 10 minutes, as a very low frequency can risk you get banned from using TzScan API for abuse. What this means is that, every n minutes, TzScan API will be queried to see if a cycle change happened. If so, TAPS will make rewards distribution to delegators. Just set it to 10 minutes.
Username and Password are used to restrict access to TAPS, as a security measure. It is advised to immediately change default username and password after installation. Only one user can be configured to use TAPS.
Lucee Server Port — You should only change the Lucee Server Port if you have installed Lucee Server to work with another port number. Otherwise, leave it as the default 8888.
Tezos base-dir, Tezos-node alias and Path to Tezos-client — Another extremely important fields. These will be used by TAPS to dinamically build the transfer command that will be passed to tezos-client to be executed. When you click TEST button, you will be able to see in the text area below, the built transfer command simulation. If TAPS is able to run the command, a green checkmark will appear, togheter with the SAVE button. Just press SAVE to continue.
Update (v1.1.1): It is far easier and more flexible to use Taps with a Native Wallet configured. Choose the “native wallet” option and this way you may ignore the previous paragraph comments.
If everything went fine, then we will get to this congratulations screen:
This confirms that TAPS was configured correctly and is able to run. Now you can go through the menu options, like REWARDS, DELEGATORS, FEES and PAYMENTS. The scheduled-task will be executing in the background. So, if it did not had time to fill the local database tables, you will see something like this:
After TzScan.io fetch has completed, the information about REWARDS, DELEGATORS and FEES will show:
The DELEGATORS screen shows a list of all the baker’s delegators, its balance as snapshoted in the rewards-pending cycle, its share based in the total staking value, the rewards each one is going to receive, the fee charged (as first configured in SETUP), and the actual value the delegator is going to receive (without fee). Note that the calculation, rather than rounding the value, truncates it. So a value of 2.928 XTZ will turn to 2.92 XTZ. In future TAPS versions, this will be a parameter configured by the baker (rounding or truncating values).
The FEES page will allow the baker to edit how much fee to charge individually for each delegator. So, if we change the first one to, say 5%, and go back to DELEGATOR page, it will have been updated:
Conclusion
This is basically what is needed to run Taps successfully. After this step by step guide, Taps will be running on background, waiting for next cycle turn, when then it will trigger its action (and do payments automatically).
Latest version (v1.1.1)
Taps v1.1.1 has some advanced new features:
- Batch payments
Taps will group all transactions in a collection in memory. After that, it will send an unique operation with n transactions inside. This is far more efficient than sending transactions one by one, as it is more failure resistant. It is also faster. After payments have been done for a cycle, check your baker’s address transactions on tzScan.io. You will notice that all last payment transactions share the same hash and timestamp. That confirms they were sent at the same time, as a batch.
- Bond pool management
You may register all of your bond pool participants, their individual XTZ quantity they’ve contributed to the pool, and define an administrative fee to be charged from each one. Also, you may consider one of the pool members as the manager. The manager will be paid with the administrative fee. If you turn on the bond pool payment option and have set up its members correctly, Taps, after paying the delegators, will distribute the remaining rewards to the bond poolers: Suppose your node earned 100 XTZ in rewards for cycle 140. Imagine that 80 XTZ were paid to delegators. The remaining 20 XTZ will be then distributed to your bond poolers.
- Advanced “Repay” button
Well, there is always a (small) chance that things go wrong. Imagine if, for some unexpected reason, Taps did not pay your delegators in a cycle. We then created the “Repay” button that do exactly that: If Taps did not work in a cycle, just go to Advanced menu option and click the Repay button. Taps will do the payments for that cycle again. But, remember: Before using this feature, always wait one hour or two to see if Taps really missed a cycle payment.
