Skip to content

An easily deployable service to monitor mission-critical SPL token accounts

License

Notifications You must be signed in to change notification settings

Bonfida/vault-watcher

Repository files navigation

Vault watcher



Monitoring critical spl-token accounts in real time



Table of contents


  1. Introduction
  2. Usage
  3. Configuration
  4. Configuration examples
  5. Grafana



Introduction


This security utility can be deployed as a container on a server to enable the monitoring of mission-critical native sol, spl-token and program accounts. Thanks to compatibility with Slack notifications, it constitutes the basis for a simple early warning system able to detect suspicious variations in account balances and deployments. As such, it can help detect critical bugs in production systems, as well as intentional attacks resulting from contract exploits, key theft, rogue agents/teams, etc.


Usage


Although the vault-watcher service can be used directly as a binary with a custom postgres instance, we recommend using docker-compose.

git clone [email protected]:Bonfida/vault-watcher.git
cd vault-watcher
cp _accounts.json accounts.json
cp _config.json config.json
cp _.env .env

The accounts.json and config.json should then be edited to configure the service. Optionally, the .env file can be edited as well. Once this is done, we start the docker containers.

sudo docker-compose build
sudo docker-compose up

The Postgres database can be directly accessed. In addition, a grafana instance with a simple provisioned dashboard can be found running at http://localhost:3000 by default.


Configuration


config.json

Field Name Type Description
endpoint string URL for the Solana RPC endpoint to connect to
refreshPeriod integer Period between account polls in milliseconds. All polls are written to the database.

accounts.json

An array of accounts objects containing

Field Name Type Description
name string User-readable identifier for the account to monitor. Maximum length is 50 characters.
address string The public key in base58 format for the account to monitor
maxChange float (Optional) The maximum allowable amplitude of balance change (in UiAmount, or Sol for native sol accounts). Only to be specified for a vault account
maxChangePeriod integer (Optional) Maximum number of milliseconds over which a maxChange balance variation is allowed without triggering a notification. Only to be specified for a vault account

.env

The .env file is used to define additional configuration through environment variables.

Var name Description
POSTGRES_PASSWORD Password for direct access to the underlying balance history database
DB_PORT Port number for the accessible locahost postgres database
GRAFANA_PORT Port number on localhost for the grafana interface
SLACK_URL Slack hook url used to push balance notifications to a Slack channel

Configuration examples


For example, if your endpoint is https://solana-api.projectserum.com and you want to poll data every 5s:

{
  "refreshPeriod": 5000,
  "endpoint": "https://solana-api.projectserum.com"
}

For example if you want to monitor 2Av1qmnqjLcnA9cpNduUL9BQcitobBq1Fiu7ZA4t45a6 and allow a max variation of 1,000 tokens every 5s while monitoring the program account 6XmmYz2gxHRPzh4yUZKiqkifEMbscS2k2ZC3bj6Amdpp:

{
  "accountType": "vault",
  "address": "2Av1qmnqjLcnA9cpNduUL9BQcitobBq1Fiu7ZA4t45a6",
  "maxChange": 1000,
  "maxChangePeriod": 5000,
  "name": "My token (or native sol) account"
},
{
  "accountType": "program",
  "address": "6XmmYz2gxHRPzh4yUZKiqkifEMbscS2k2ZC3bj6Amdpp",
  "name": "My program account"
}

Grafana


Historical balances can be monitored using Grafana through port 3000