In the last month, we, engineers in Tezos SouthEast Asia, Nine chapters, and DaiLambda, have worked on TzScan OS, the Open Source version of TzScan (the commit hash 5a1cae6b) to provide an easy way to install it and evaluate it.

TzScan is a Tezos block explorer developed by OCamlPro. They have their own instance of TzScan at https://tzscan.io/. Let’s call it TzScan Pro.

During the installation effort and evaluation of TzScan OS, we have noticed many functionalities of TzScan Pro are missing in TzScan OS. In this article, we summarize our findings (or non-findings).

Tezos businesses such as baking and app devs depending on TzScan Pro may not work properly with TzScan OS. If you own such a business, we strongly recommend you to test your system with TzScan OS, in order to understand precisely what you are depending on.

TzScan OS lacks lots of features of TzScan Pro

Once you deploy your TzScan OS servers then soon you will find that its web pages lack lots of things which should be available in TzScan Pro: marketcap info, staking ratio, roll owners, baking rights, etc. This is not due to your misconfiguration:

TzScan OS lacks many features which are available in TzScan Pro.

TzScan OS consists of 3 programs:

  • Crawler, which queries information from Tezos nodes periodically and writes it to PostgreSQL tables.
  • API-server, which reads these DB tables and provides analytics.
  • UI code, which renders browser pages, asking analytics from the API-server.

The API-server and the UI code of TzScan OS seem to be identical (or almost identical) to TzScan Pro: there are the codes which correspond with all the visual components of TzScan Pro.

The problem is the crawler. It does not fill all the tables used by the API-server.

In the code of TzScan OS, there are 2 OCaml modules called src/db/writer.ml and src/db/reader.ml, which are used by the crawler to write data and the API-server to read them respectively. Even if you are not proficient in OCaml, you can find there are asymmetries in the writer and reader modules: lots of table names appear in the writer code never appear in the reader code.

Here are the DB tables TzScan OS builds at its installation with the existences of its reader and writer code. (Disclaimer: this is done by simple string match and not by thorough code analysis, but we think this is quite near to the reality):

Table name Reader Writer
activation V V
activation_all V V
activation_balance V V
activation_last V V
balance_from_balance_updates V V
balance_updates V V
ballot V V
block V V
block_operation V V
count_info V V
crawler_activity V V
cycle_count V V
cycle_count_baker V V
delegation V V
delegation_all V V
delegation_last V V
double_baking_evidence V V
double_endorsement_evidence V V
endorsement V V
endorsement_all V V
endorsement_last V V
fee_block V V
header V V
info V V
operation V V
operation_count_user V V
origination V V
origination_all V V
origination_last V V
peers V V
proposal V V
protocol V V
reveal V V
reveal_all V V
reveal_last V V
seed_nonce_revelation V V
switch V V
tezos_user V V
transaction V V
transaction_all V V
transaction_last V V
user_alias V V
vol_block V V
coingecko_exchange V -
context_totals V -
day_context V -
level_rights V -
marketcap V -
quorum V -
snapshot_deleguees V -
snapshot_owner V -
snapshot_rolls V -
snapshot_voting_rolls V -
top_balances V -
top_frozen_balances V -
top_frozen_deposits V -
top_frozen_rewards V -
top_paid_bytes V -
top_staking_balances V -
top_total_balances V -
top_total_delegated V -
top_total_delegators V -
top_total_frozen_fees V -
top_used_bytes V -
authorized - -
faucet - -
snapshot_deleguees_balanc_deprecated - -
user_accounts_deprecated - -
user_bookmarks_deprecated - -
user_sessions_deprecated - -

Apart from 6 tables which never appear either in reader or in writer, 21 tables of 64, almost 13 of them, lack its writer codes. Many of these tables without writers seem to relate with the missing elements in TzScan OS browser pages.

Based on this analysis, we had to conclude that OCamlPro’s TzScan instance TzScan Pro, https://tzscan.io, must have a closed source crawler to fill these tables which are left empty in TzScan OS.

Many of TzScan OS’s APIs return empty results

This lack of data does not only affect the TzScan OS browser pages but also its APIs.

Here are APIs we found returning empty arrays or 0 in TzScan OS, where they return something more meaningful in TzScan Pro. Please note that this list may not be exhaustive, and the empty arrays or 0 may not mean that APIs are broken:

Description API path
Market Cap GET /v3/marketcap
Snapshotted levels GET /v3/snapshot_levels
Snapshotted blocks GET /v3/snapshot_blocks
Number of snapshotted blocks GET /v3/nb_snapshot_blocks
Rolls by cycle GET /v3/rolls_history/{account_hash}
Rolls GET /v3/roll_number/{account_hash}
Account votes GET /v3/votes_account/{account_hash}
Rights GET /v3/baking_rights
Number of rights GET /v3/number_baking_rights
Baking Rights GET /v3/baker_rights/{account_hash}
Number of baking rights GET /v3/number_baker_rights/{account_hash}
Baking rights by cycle GET /v3/cycle_baker_rights/{account_hash}
Number of endorsing rights GET /v3/number_endorser_rights/{account_hash}
Endorsing Rights GET /v3/endorser_rights/{account_hash}
Endorsing rights by cycle GET /v3/cycle_endorser_rights/{account_hash}
Required deposits by cycle GET /v3/required_balance/{account_hash}
Bakings for a cycle GET /v3/bakings/{account_hash}
Endorsements for a cycle GET /v3/bakings_endorsement/{account_hash}
Number of endorsements for a cycle GET /v3/number_bakings_endorsement/{account_hash}
Delegate rewards GET /v3/rewards_split_cycles/{account_hash}
Number of cycles with rolls GET /v3/nb_cycle_rewards/{account_hash}
Number of delegators for a cycle GET /v3/nb_delegators/{account_hash}
Delegator rewards GET /v3/delegator_rewards/{contract_hash}
Delegator rewards (detailed) GET /v3/delegator_rewards_with_details/{contract_hash}
Number of cycles as delegator GET /v3/nb_cycle_delegator_rewards/{contract_hash}
Period info GET /v3/voting_period_info
Voters total GET /v3/total_voters/{period}
Proposals GET /v3/proposals
Number of proposals GET /v3/nb_proposal
Proposal votes GET /v3/proposal_votes/{proposal_hash}
Number of proposal votes GET /v3/nb_proposal_votes/{proposal_hash}
Vote totals GET /v3/total_proposal_votes/{period}
Number of ballot votes GET /v3/nb_ballot_votes/{proposal_hash}

If your system is dependent on these APIs of TzScan Pro, TzScan OS may not provide a back-up for you.

Check it yourself

We recommend the community to deploy your own TzScan OS instances. Especially if you are a Tezos business owner, you should check your system with TzScan OS to see whether TzScan OS can be a substitute of TzScan Pro.

TzScan OS installer script

To make it easy to install TzScan OS, we have created an installer script and put it at:

TzScanInstaller: https://gitlab.com/tezos-southeast-asia/tzscaninstaller

A community fork of TzScan OS

Note that TzScanInstaller does not use the original TzScan OS but a fork at https://gitlab.com/tezos-southeast-asia/tzscan. This is not to extend TzScan OS to cover the missing pieces, but to provide support with minimum fixes for building issues and critical bugs.

Please report any problems, questions and merge requests to these repositories.

Public TzScan OS instances

Having more and more TzScan OS instances is the best for the community, but if you have difficulties of building it or maintaining an instance, you can try the following TzScan OS instances publicly available. Mind that they are maintained by volunteers: please do not bother OCamlPro by reporting issues of these instances.

Mainnet instances

Alphanet instances

Zeronet instances