npm package: @interlay/polkabtc-stats
Description: This repository serves as a monitoring solution and API wrapper of ongoing events in the [PolkaBTC parachain](https://polkabtc.io/).
Latest version: 0.3.3

# PolkaBTC Stats API

This repository serves as a monitoring solution and API wrapper of ongoing events in the [PolkaBTC parachain](https://polkabtc.io/).


### 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](https://github.com/interlay/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](https://www.npmjs.com/package/pg-native) for more details.

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

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

Start the service with:

```shell
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).

```shell
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](https://github.com/interlay/btc-parachain) setup postgresql and run the
included monitoring service.

```shell
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.

```shell
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

```typescript
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`.