tokenbridge/monitor/README.md

POA TokenBridge / Monitor

Tool for checking balances and unprocessed events in bridged networks.

Overview

Please refer to the POA TokenBridge overview first of all.

• Deployed version serves several monitor configurations:
  • https://bridge-monitoring.poa.net/poa
  • https://bridge-monitoring.poa.net/xdai
  • https://bridge-monitoring.poa.net/wetc
  • https://bridge-monitoring.poa.net/amb-dai
  • https://bridge-monitoring.poa.net/amb-poa

This tool allows you to spin up a NODE.JS server to monitor for health of the TokenBridge contracts: check for the balance difference, discover inconsistency in the validators list, catch unhandled transactions.

Examples

Example of an API

• GET / - check contract balances & tx numbers

{
    "home": {
        "balance": "3710077.6896438415780044",
        "deposits": 481,
        "withdrawals": 221
    },
    "foreign": {
        "totalSupply": "3710077.6896438415780044",
        "deposits": 481,
        "withdrawals": 221
    },
    "balanceDiff": 0,
    "lastChecked": 1529511982,
    "depositsDiff": 0,
    "withdrawalDiff": 0
}

• GET /validators - check validators balances

{
    "home": {
        "validators": {
            "0x35DC13c72A9C09C8AEEBD0490C7228C43Ccc38Cd": {
                "balance": "19.994900374",
                "leftTx": 66649667913333,
                "gasPrice": 1
            },
            "0x5D44BC8642947685F45004c936245B969F9709a6": {
                "balance": "19.993736069",
                "leftTx": 66645786896666,
                "gasPrice": 1
            },
            "0x284877074B986A78F01D7Eb1f34B6043b1719002": {
                "balance": "19.995139875",
                "leftTx": 66650466250000,
                "gasPrice": 1
            }
        },
        "requiredSignatures": 2
    },
    "foreign": {
        "validators": {
            "0x35DC13c72A9C09C8AEEBD0490C7228C43Ccc38Cd": {
                "balance": "19.084023268196",
                "leftTx": 28915,
                "gasPrice": 2.2
            },
            "0x5D44BC8642947685F45004c936245B969F9709a6": {
                "balance": "19.086724777075",
                "leftTx": 28919,
                "gasPrice": 2.2
            },
            "0x284877074B986A78F01D7Eb1f34B6043b1719002": {
                "balance": "19.050074813935",
                "leftTx": 28863,
                "gasPrice": 2.2
            }
        },
        "requiredSignatures": 2
    },
    "requiredSignaturesMatch": true,
    "validatorsMatch": true,
    "lastChecked": 1529512164
}

• GET /eventsStats - check unprocessed events

{
    "onlyInHomeDeposits": [],
    "onlyInForeignDeposits": [],
    "onlyInHomeWithdrawals": [],
    "onlyInForeignWithdrawals": [],
    "lastChecked": 1529512436
}

How to run

Setup

1. Initialize the monorepository.

2. Go to the monitor sub-repository:

cd monitor

3. Create .env file:

cp .env.example .env

Please refer to Configuration for details on configuration parameters.

Run web interface

Using Yarn:

yarn start

You can run web interface via pm2 or similar supervisor program.

Using Docker:

• to run it very first time (or after changes related to the monitor code):

  docker-compose -f docker-compose-build.yml -f docker-compose.yml up -d --build
  

• next time (or in case of usage of an official docker image)

  docker-compose up -d
  

• The application will run on http://localhost:MONITOR_PORT/MONITOR_BRIDGE_NAME, where MONITOR_PORT and MONITOR_BRIDGE_NAME are specified in your .env file.
• To enabled debug logging, set DEBUG=1 variable in .env.

Preparing statistic about balances of bridge contracts and validators, get unprocessed events

Using Yarn:

yarn check-all

Using Docker:

docker run --rm --env-file .env -v $(pwd)/responses:/mono/monitor/responses \
  poanetwork/tokenbridge-monitor:latest /bin/bash -c 'yarn check-all'

As soon as the process finishes, use the URL described above to get the statistic.

Cron

You can create cron job to run workers (see crontab.example for reference):

Ad-hoc monitoring

There is a possibility to get bridge statistics without running the web interface use the commands provided above. In this case the results will be located in the responses directory.

Build the image without running the monitor

To build the image change the directory:

cd monitor

And run the docker composer:

docker-compose -f docker-compose-build.yml build

Linting

Running linter:

yarn lint

Contributing

See the CONTRIBUTING document for contribution, testing and pull request protocol.

License

This project is licensed under the GNU Lesser General Public License v3.0. See the LICENSE file for details.