PolkaBTC Stats API

This repository serves as a monitoring solution and API wrapper of ongoing events in the PolkaBTC parachain.

Monitoring

polkabtc-stats includes a service to extract all events from the BTC-Parachain into a PostgreSQL database for further processing.

When first starting, the service connects to a BTC-Parachain archive node to process all events from genesis and stores them into a PostgreSQL database. When it reaches the current block, it goes into a monitoring mode such that only the latest events from incoming blocks are parsed. On restarting, the service first checks the last processed block in the database and will continue to process events from blocks not yet in the database.

API wrapper

polkabtc-stats also provides an API wrapping around the PostgreSQL database, to aggregate and make available historic data about PolkaBTC parachain operation.

When the service is running, queries to the PostgreSQL database can be made. The package provides pre-defined views to display relevant statistics. This includes for example:

• All issue requests
• All redeem requests
• Percentage of completed issue requests
• Percentage of completed redeem requests

A note on decentralization

Anybody can freely host their own instance of this database and use it to serve a local version of the dashboards contained in the official PolkaBTC UI. Interlay is hosting its own version for monitoring purposes.

Usage

For the current instructions on running against a local parachain alongside the monitoring service, see the Testing section below.

Prerequisite: As the pg-native driver is used for the database, you need to ensure libpq is installed locally; on some systems, this may require installing the development version of relevant postgresql packages in addition to postgresql itself (e.g. libpq-dev or postgresql-libs-devel). See the NPM page for more details.

Ensure the proper environment variables for the PostgreSQL connection are set, e.g.:

PGHOST=yourhost
PGPORT=15432
PGDATABASE=database
PGUSER=youruser
PGPASSWORD=yourpassword

Start the service with:

export PGSSLMODE=require # for secure connections

yarn install
yarn build # generate the routes and run typechecking
yarn dev # start the server with file watching

Then navigate to localhost:3007/docs for the SwaggerUI, or to the defined routes to make use of the APIs.

Deployment

Run yarn start instead.

Client

For client generation, ensure java is in the path (this is not necessary just to run the stats server).

yarn client

This builds the client generated from the OpenAPI spec (which can then be published using yarn publish).

Testing

To build the database from the btc-parachain setup postgresql and run the included monitoring service.

docker run --rm --name postgres \
    -p 5432:5432 \
    -e POSTGRES_USER=user \
    -e POSTGRES_PASSWORD=password \
    postgres:11

export PGDATABASE="postgres"
export PGUSER="user"
export PGPASSWORD="password"

MONITOR=1 yarn dev

To persist the database, mount a local volume on the docker container.

mkdir -p $HOME/docker/volumes/postgres
docker run --rm --name postgres \
    -p 5432:5432 \
    -e POSTGRES_USER=user \
    -e POSTGRES_PASSWORD=password \
    -v $HOME/docker/volumes/postgres:/var/lib/postgresql/data \
    postgres:11

Usage

import * as polkabtcStats from "@interlay/polkabtc-stats";
const statsApi = new polkabtcStats.StatsApi(new polkabtcStats.Configuration({ basePath: "http://localhost:3001" }));
const issues = (await statsApi.getTotalSuccessfulIssues()).data;

Autogenerated paths

src/ is the only directory containing hand-written code. Do not edit files in the other directories.

• build/ contains the OpenAPI server (including the json definition and the routes to be served), generated from the definitons in src. Generated using yarn build.
• client/ contains the generated typescript client, as an intermediate step in packaging the client.
• dist/ contains the compiled client, publishable as an npm package. Generated (alongside client/) using yarn client.