README.md

The Open League

This repository contains code for The Open League metrics calculation.

Architecture

The Open League consists of multiple leaderboards showcasing project rankings. These rankings are based on specific metrics and are calculated for a particular season, a set period of time with a defined list of projects and rules.

The primary objective of this repository is to establish a Domain Specific Language (DSL) for leaderboards, projects, and seasons. Using this DSL, all ranks can be calculated through backends. A backend is an implementation of metrics calculation based on a specific data source. Currently, there are three backends:

• re:doubt DB, which is based on ton-indexer and Tonalytica. It is used for all leaderboards except of DeFi. It is deprecated since S6.
• toncenter_cpp, which is based on ton-index-worker by Toncenter and TON-ETL.
• DefiLlama with on-chain data from Tonapi - used for the DeFi Leaderboard.

Main entities:

• Metric - used for the App Leaderboard, a simple way to describe on-chain mechanics for applications. Each metric must contains backend-specific implementation. (see an example)
• Backend - metrics calculation backend per leaderboard.
• ProjectStats - results of calculation, contains key-value dict with metrics values
• Project - all information about particular project. For applications must contain all possible interactions and unique off-chain analytics tag.
• SeasonConfig - season config: time period, list of projects, scoring formula, etc..
• ScoreModel - final formula to get scores for each project based on metrics

Every project must have an icon, icon must be present in the projects/icons folder. Icon name template is {leaderboard}_{project_name}.{extension}, where:

• leaderboard - value from SeasonConfig.leaderboard
• project_name - project name (Project.name), in lower-case
• extension - svg or png. In case of png size must be 100x100 px.

Seasons

List of the seasons supported with the leaderboard links

Season	Results
S3.5 - test season (no actual competition), between S3 and S4.	Tokens: HTML, JSON Apps: HTML, JSON
S4 - Methodology	Tokens: HTML, JSON Apps: HTML, JSON DeFi: HTML, JSON NFT: HTML, JSON
S5 - Methodology	Tokens: HTML, JSON Apps: HTML, JSON DeFi: HTML, JSON NFT: HTML, JSON
S6 - Methodology	Apps: HTML, JSON DeFi TVL: HTML, JSON DeFi Volume: HTML, JSON NFT: HTML, JSON DeFi scores

Adding metrics for your project

To add new project one need to create a file in projects/{type}/{slug.py} folder, where type is apps or token and slug is project name.

To add more contracts please find your project file in projects folder and add metrics you need. The full list of supported metrics is here.

Running configuration

To run metrics calculation one needs to use existing SeasonConfig and configured backend. In general backends require some params and resources preconfigured (like DB connection). Simple example of running different backends is provided in test_runnger.py.

Re:doubt backend

One need to pass postgres db connection. Below is an example for running via Apache Airflow:

postgres_hook = PostgresHook(postgres_conn_id="db")
backend = RedoubtAppBackend(postgres_hook.get_conn())
results = backend.calculate(S4_app)
OUTPUT_JSON = "output.json"
OUTPUT_HTML = "output.html"
render = JsonRenderMethod(OUTPUT_JSON)
render.render(results, season_config)
render = HTMLRenderMethod(OUTPUT_HTML)
render.render(results, season_config)

DeFiLlama backend

It requires data from DeFiLlama (public, doesn't require auth) and tonapi (API key is recommended). Also, contract-executor tool is required. Example of running config:

backend  = DefillamaDeFiBackend(
                tonapi=TonapiAdapter("ABCD...."),
                executor=ContractsExecutor("http://localhost:9090/execute")
            )
results = backend.calculate(S4_defi)
...