Coin-Tracker

Coin-Tracker is a tool that monitors the all coin transfer activity of the defined coin types and raises an alert when coin transfer amount is greater than the expected defined amount or alerting rule related to coin transfer meets.

The main objective of the coin-tracker tool is to identify transfer actions performed by crypto whales, so we can take actions against that and reduce any type of monitory lose.

This tool works as an service and continuously fetches 0x1::coin::CoinDeposit events from the move-layer, processes them, and determines whether an alert should be triggered based on defined rules.

Currently, Slack is used as alerting channel or medium and as a result of the alert, message in the defined slack channel is sent.

Alert Types

Alert types refers to the different types of alert created when specific alert condition meets. In coin-tracker tool, under the hood when conditions associated with the coin transfer meets alert is created.

There are two types of alerts:

Single Transfer Alert:

This alert is created, when more or equal amount of x (transfer amount defined for alert) coins of defined types are moved or transferred. When the transfer_amount >= AlertAmounts::single_transfer_alert_amount this alert created
Multi Transfer Alert:

This alert will be created when more or equal amount of x (sum of total transfer happened in d duration) coins of defined types are moved or transferred in less than d duration. When the multi_transfer_sum >= AlertAmounts::multi_transfer_alert_amount and this condition meets in less than CoinInfo::time_window_size_in_secs this alert will be created.

How It Works in simple abstract

Listens for CoinDeposit events on the blockchain.
Evaluates incoming data against the alerting rules.
Sends formatted messages to a configured Slack channel when thresholds are crossed.

Prerequisites

Here is the list of few prerequisites to run coin-tracker tool,

Rust setup to create binaries, if you haven't done follow Rust installation page.
Create slack channel webhook which will be used by coin-tracker to send alert messages on it, if you haven't done follow this.

Running tool

Building `Coin-Tracker` binary from source

If you have followed setup so you can ignore this section and move onto next section.

Once Rust is installed, you can use the following commands to build the binaries:

Clone the repository:

git clone https://github.com/Entropy-Foundation/supra-toolbox.git

Build the binary:

cargo build --package coin-tracker --release

Prepare `coin_info_list.json` file

The coin_info_list.json file contains the information about list of coins to be monitored, once the tool will start it will start monitoring coins defined in this file, later we can add or remove any coin from monitoring or modify any information related to that by interacting with API endpoints.

Example Structure of the file:

[
    {
        "coin_type": "0x1::supra_coin::SupraCoin",
        "alert_amounts": {
            "single_transfer_alert_amount": 100000000,
            "multi_transfer_alert_amount": 1000000000
        },
        "time_window_size_in_secs": 100
    }
]

The above shown example structure only contains information about the SupraCoin we can add information about other coins as well.

CoinInfo Attributes:

coin_type: The type of the coin, the uniquely identifies every coin on network,
alert_amounts: Alert amounts to trigger alerting. a. single_transfer_alert_amount: Amount applies on a single transfer operation. If the coin's transfer_amount >= single_transfer_alert_amount, the the alert will be sent.

b. multi_transfer_alert_amount: Amount applies on multi_transfer_sum (sum of the transfer_amount of all of transfer operation performed during time-window).

If the sum of multi_transfer_sum >= multi_transfer_alert_amount and time window is active,the the alert will be sent.
time_window_size_in_secs: Amount of time to consider for multi-transfer related alerting. Coin-specific imaginary time-window will be maintained for every user and the window size will be time_window_size_in_secs. When the sum of specific coin's total value transfer done by a user is greater than AlertAmounts::multi_transfer_alert_amount in less than time_window_size_in_secs amount of seconds so the alert will be created and the window will be reset.

Export Slack channel webhook

export WHALE_ALERT_CHANNEL_SLACK_WEBHOOK=<Add your slack channel webhook url>

Run the binary

Now as the last step just run the binary of the coin-tracker by running below given command and it is assumed that you are in project root directory.

# Please feel free to run `./target/debug/coin-tracker --help` to know more about the cli tool
./target/debug/coin-tracker --rpc-url <Target rpc node rest endpoint> --coin-info-list-file-path <Path of the `coin_info_list` file> > coin_tracker.log 2>&1

Example:

./target/debug/coin-tracker --rpc-url https://rpc-autonet.supra.com/ --coin-info-list-file-path ./trackers/coin-tracker/coin_info_list.json > coin_tracker.log 2>&1

API Endpoints

/getCoinAlertAmountInfo: To get latest information about list of monitoring coins.

Example:
```
curl  -X GET \
'http://127.0.0.1:8000/getCoinAlertAmountInfo' | jq
```

/addCoin: To add new coin for monitoring.

Example:

curl  -X POST \
'http://127.0.0.1:8000/addCoin' \
--header 'Content-Type: application/json' \
--data-raw '    {
        "coin_type": "0xc95bff703ac1fc3ffdc10570784581cbb734be31c5d947d2878e5f8ff9447910::coin::WBTC",
        "alert_amounts": {
            "single_transfer_alert_amount": 500000000000,
            "multi_transfer_alert_amount": 50000000000000
        },
        "time_window_size_in_secs": 120
    }'

/removeCoin: To remove existing coin from monitoring.

Example:

curl  -X POST \
'http://127.0.0.1:8000/removeCoin' \
--header 'Content-Type: application/json' \
--data-raw '    {
        "coin_type": "0xc95bff703ac1fc3ffdc10570784581cbb734be31c5d947d2878e5f8ff9447910::coin::WBTC"
    }'

/updateCoinAlertAmounts: To update alerting rules and information the existing coin type.

Example:

curl  -X POST \
'http://127.0.0.1:8000/updateCoinAlertAmounts' \
--header 'Content-Type: application/json' \
--data-raw '    {
        "coin_type": "0xc95bff703ac1fc3ffdc10570784581cbb734be31c5d947d2878e5f8ff9447910::coin::WBTC",
        "alert_amounts": {
            "single_transfer_alert_amount": 900000000000,
            "multi_transfer_alert_amount": 90000000000000
        },
        "time_window_size_in_secs": 120
    }'

Supra-Toolbox Documentation