{"id":18300930,"url":"https://github.com/bonfida/vault-watcher","last_synced_at":"2025-04-05T14:30:47.651Z","repository":{"id":37904142,"uuid":"478678525","full_name":"Bonfida/vault-watcher","owner":"Bonfida","description":"An easily deployable service to monitor mission-critical SPL token accounts","archived":false,"fork":false,"pushed_at":"2024-06-14T04:05:05.000Z","size":701,"stargazers_count":31,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-21T05:32:51.529Z","etag":null,"topics":["monitoring","security","solana","spl-token"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Bonfida.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-06T18:19:39.000Z","updated_at":"2025-03-14T01:50:20.000Z","dependencies_parsed_at":"2024-06-13T14:06:22.757Z","dependency_job_id":"f3dbf7e5-ee18-4e1f-8546-4207e4ac1918","html_url":"https://github.com/Bonfida/vault-watcher","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bonfida%2Fvault-watcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bonfida%2Fvault-watcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bonfida%2Fvault-watcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bonfida%2Fvault-watcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bonfida","download_url":"https://codeload.github.com/Bonfida/vault-watcher/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247352254,"owners_count":20925236,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["monitoring","security","solana","spl-token"],"created_at":"2024-11-05T15:13:51.168Z","updated_at":"2025-04-05T14:30:46.901Z","avatar_url":"https://github.com/Bonfida.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eVault watcher\u003c/h1\u003e\n\u003cbr /\u003e\n\u003cp align=\"center\"\u003e\n\u003cimg width=\"250\" src=\"https://i.imgur.com/nn7LMNV.png\"/\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://twitter.com/bonfida\"\u003e\n\u003cimg src=\"https://img.shields.io/twitter/url?label=Bonfida\u0026style=social\u0026url=https%3A%2F%2Ftwitter.com%2Fbonfida\"\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cbr /\u003e\n\n\u003ch2 align=\"center\"\u003eMonitoring critical spl-token accounts in real time\u003c/h2\u003e\n\u003cbr/\u003e\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/Docker-2CA5E0?style=for-the-badge\u0026logo=docker\u0026logoColor=white\" /\u003e\n\u003cimg src=\"https://img.shields.io/badge/Rust-000000?style=for-the-badge\u0026logo=rust\u0026logoColor=white\" /\u003e\n\u003cimg src=\"https://img.shields.io/badge/Grafana-F2F4F9?style=for-the-badge\u0026logo=grafana\u0026logoColor=orange\u0026labelColor=F2F4F9\" /\u003e\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\u003ch2 align=\"center\"\u003eTable of contents\u003c/h2\u003e\n\u003cbr /\u003e\n\n1. [Introduction](#introduction)\n2. [Usage](#usage)\n3. [Configuration](#configuration)\n4. [Configuration examples](#configuration-examples)\n5. [Grafana](#grafana)\n\n\u003cbr /\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"assets/overview.png\" width=\"90%\" /\u003e\n\u003c/p\u003e\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\u003ca name=\"introduction\"\u003e\u003c/a\u003e\n\u003ch2 align=\"center\"\u003eIntroduction\u003c/h2\u003e\n\u003cbr /\u003e\n\nThis 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.\n\n\u003cbr /\u003e\n\u003ca name=\"usage\"\u003e\u003c/a\u003e\n\u003ch2 align=\"center\"\u003eUsage\u003c/h2\u003e\n\u003cbr /\u003e\n\nAlthough the `vault-watcher` service can be used directly as a binary with a custom postgres instance, we recommend using `docker-compose`.\n\n```bash\ngit clone git@github.com:Bonfida/vault-watcher.git\ncd vault-watcher\ncp _accounts.json accounts.json\ncp _config.json config.json\ncp _.env .env\n```\n\nThe `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.\n\n```bash\nsudo docker-compose build\nsudo docker-compose up\n```\n\nThe 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.\n\n\u003cbr /\u003e\n\u003ca name=\"configuration\"\u003e\u003c/a\u003e\n\u003ch2 align=\"center\"\u003eConfiguration\u003c/h2\u003e\n\u003cbr /\u003e\n\n### `config.json`\n\n| Field Name    | Type    | Description                                                                          |\n| ------------- | ------- | ------------------------------------------------------------------------------------ |\n| endpoint      | string  | URL for the Solana RPC endpoint to connect to                                        |\n| refreshPeriod | integer | Period between account polls in milliseconds. All polls are written to the database. |\n\n### `accounts.json`\n\nAn array of accounts objects containing\n\n| Field Name      | Type               | Description                                                                                                                                                    |\n| --------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| name            | string             | User-readable identifier for the account to monitor. Maximum length is 50 characters.                                                                          |\n| address         | string             | The public key in base58 format for the account to monitor                                                                                                     |\n| 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                      |\n| 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 |\n\n### `.env`\n\nThe .env file is used to define additional configuration through environment variables.\n\n| Var name          | Description                                                           |\n| ----------------- | --------------------------------------------------------------------- |\n| POSTGRES_PASSWORD | Password for direct access to the underlying balance history database |\n| DB_PORT           | Port number for the accessible locahost postgres database             |\n| GRAFANA_PORT      | Port number on localhost for the grafana interface                    |\n| SLACK_URL         | Slack hook url used to push balance notifications to a Slack channel  |\n\n\u003cbr /\u003e\n\u003ca name=\"configuration-examples\"\u003e\u003c/a\u003e\n\u003ch2 align=\"center\"\u003eConfiguration examples\u003c/h2\u003e\n\u003cbr /\u003e\n\nFor example, if your endpoint is `https://solana-api.projectserum.com` and you want to poll data every `5s`:\n\n```json\n{\n  \"refreshPeriod\": 5000,\n  \"endpoint\": \"https://solana-api.projectserum.com\"\n}\n```\n\nFor example if you want to monitor `2Av1qmnqjLcnA9cpNduUL9BQcitobBq1Fiu7ZA4t45a6` and allow a max variation of `1,000` tokens every `5s` while monitoring the program account `6XmmYz2gxHRPzh4yUZKiqkifEMbscS2k2ZC3bj6Amdpp`:\n\n```json\n{\n  \"accountType\": \"vault\",\n  \"address\": \"2Av1qmnqjLcnA9cpNduUL9BQcitobBq1Fiu7ZA4t45a6\",\n  \"maxChange\": 1000,\n  \"maxChangePeriod\": 5000,\n  \"name\": \"My token (or native sol) account\"\n},\n{\n  \"accountType\": \"program\",\n  \"address\": \"6XmmYz2gxHRPzh4yUZKiqkifEMbscS2k2ZC3bj6Amdpp\",\n  \"name\": \"My program account\"\n}\n```\n\n\u003cbr /\u003e\n\u003ca name=\"grafana\"\u003e\u003c/a\u003e\n\u003ch2 align=\"center\"\u003eGrafana \u003c/h2\u003e\n\u003cbr /\u003e\n\nHistorical balances can be monitored using [Grafana](https://grafana.com/) through port `3000`\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"assets/grafana.png\" width=\"90%\" /\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbonfida%2Fvault-watcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbonfida%2Fvault-watcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbonfida%2Fvault-watcher/lists"}