{"id":13566830,"url":"https://github.com/cheqd/validator-status","last_synced_at":"2025-04-04T00:32:21.235Z","repository":{"id":49802898,"uuid":"491646567","full_name":"cheqd/validator-status","owner":"cheqd","description":"Network-wide validator status alerting API for cheqd mainnet. Designed to work for any Cosmos SDK network","archived":false,"fork":false,"pushed_at":"2025-03-17T07:15:17.000Z","size":278,"stargazers_count":8,"open_issues_count":5,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-20T17:06:16.003Z","etag":null,"topics":["bigdipper","cheqd","cloudflare-workers","cosmos-sdk","hacktoberfest","zapier"],"latest_commit_sha":null,"homepage":"https://validator-status.cheqd.net/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cheqd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-12T19:42:45.000Z","updated_at":"2025-01-28T10:29:34.000Z","dependencies_parsed_at":"2024-01-03T17:25:13.750Z","dependency_job_id":"59cc6753-4763-4e62-8e6d-229c12c595b5","html_url":"https://github.com/cheqd/validator-status","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":"cheqd/.github","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheqd%2Fvalidator-status","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheqd%2Fvalidator-status/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheqd%2Fvalidator-status/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheqd%2Fvalidator-status/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cheqd","download_url":"https://codeload.github.com/cheqd/validator-status/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247103290,"owners_count":20884023,"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":["bigdipper","cheqd","cloudflare-workers","cosmos-sdk","hacktoberfest","zapier"],"created_at":"2024-08-01T13:02:17.567Z","updated_at":"2025-04-04T00:32:21.228Z","avatar_url":"https://github.com/cheqd.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Cosmos SDK: Validator Status Alerts API\n\n[![GitHub license](https://img.shields.io/github/license/cheqd/validator-status?color=blue\u0026style=flat-square)](https://github.com/cheqd/validator-status/blob/main/LICENSE)\n[![GitHub contributors](https://img.shields.io/github/contributors/cheqd/validator-status?label=contributors%20%E2%9D%A4%EF%B8%8F\u0026style=flat-square)](https://github.com/cheqd/validator-status/graphs/contributors)\n\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/cheqd/.github/dispatch.yml?label=workflows\u0026style=flat-square)](https://github.com/cheqd/validator-status/actions/workflows/dispatch.yml) ![GitHub repo size](https://img.shields.io/github/repo-size/cheqd/validator-status?style=flat-square)\n\n## ℹ️ Overview\n\nMost validator status reporting software in [Cosmos SDK](https://cosmos.network/) is designed to be run *directly* by a node operator to monitor their own nodes. This typically pulls data from [the Tendermint Prometheus metrics sink](https://docs.tendermint.com/v0.34/tendermint-core/metrics.html) exposed on a node.\n\nWe wanted to build a way to monitor the status of validator nodes *globally* across the cheqd mainnet, and raise alerts in case validator nodes were losing blocks. (Validator nodes [can get jailed if they miss too many blocks](https://docs.cosmos.network/main/modules/slashing/) and their stake slashed.)\n\nThis custom API pulls data for all validator nodes from [a BigDipper block explorer](https://explorer.cheqd.io/) (e.g., [explorer.cheqd.io](https://explorer.cheqd.io/)) and repurposes/wraps [the validator condition results](https://explorer.cheqd.io/validators) into a JSON array.\n\nThe API itself can be deployed using [Cloudflare Workers](https://workers.cloudflare.com/) or compatible serverless platforms. Alerting is then achieved using Zapier (a low-code/no-code automation platform) to pipe these alerts to Slack, Discord, etc.\n\n## 🚨 Alerting via Zapier\n\nTo simplify the task of alerting via various channels (and to keep it extensible to other channels), we take the output of our validator status API and parse it via [Zapier](https://zapier.com/). This is done as a two-stage process via two separate \"Zaps\".\n\nRight now, our setup sends these details to the [cheqd Community Slack](http://cheqd.link/join-cheqd-slack) and the [cheqd Community Discord](http://cheqd.link/discord-github).\n\n1. Our validator status API sends [a webhook call to a Zapier \"Zap\"](https://zapier.com/shared/d407b10516f89da18e35b97ce3ef226bca2ad741) that listens for newly-degraded validators every hour.\n2. Lists of degraded validators are compiled using a Zapier \"Sub-Zap\" to process the data from the API into a usable format and stored in a \"digest\".\n\n\t```javascript\n\tconst body = JSON.parse(inputData.VALIDATOR_CONDITION);\n\tvar degraded = [];\n\n\tfor (let k=0; k\u003cbody.length; k++) {\n\tdegraded.push(body[k]);\n\t}\n\treturn {degraded}\n\t```\n\n3. \"Release\" any unreleased digests by using [the manual release feature in Digest by Zapier](https://zapier.com/help/create/storage-and-digests/compile-data-in-a-digest-in-zaps#release-the-content-of-the-digest).\n4. If execution has proceeded to this step, use the [Zapier App for Slack](https://zapier.com/apps/slack/integrations) and [Zapier App for Discord](https://zapier.com/apps/discord/integrations) to send a message (with formatting) to designated alert channels.\n\nYou can [copy this Zap](https://zapier.com/shared/d407b10516f89da18e35b97ce3ef226bca2ad741) to configure a similar setup for other alert channels, such as [Email by Zapier](https://zapier.com/apps/email/integrations).\n\n## 🧑‍💻🛠 Developer Guide\n\n### Architecture\n\nThis API was developed to work with [Cloudflare Workers](https://workers.cloudflare.com/), a serverless and highly-scalable platform.\n\nOriginally, this project was discussed as potentially being deployed using a serverless platform such as [AWS Lambda](https://aws.amazon.com/lambda/). However, [AWS Lambda has a cold-start problem](https://mikhail.io/serverless/coldstarts/aws/) if the API doesn't receive too much traffic or is only accessed infrequently. This can lead to start times ranging into single/double digit seconds, which would be considered an API timeout by many client applications.\n\nUsing Cloudflare Workers, these APIs can be served in a highly-scalable fashion and have much lower cold-start times, i.e., in the range of less than 10 milliseconds.\n\n### Setup\n\nThe recommended method of interacting with this repository is using [Cloudflare Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/get-started/).\n\nDependencies can be installed using NPM or any other package manager.\n\n```bash\nnpm install\n```\n\nWhile our deployment uses Cloudflare Wrangler, the application itself could be modified to run on other platforms with some refactoring.\n\n### Configuration\n\nWrangler CLI uses [`wrangler.toml` for configuring](https://developers.cloudflare.com/workers/wrangler/configuration/) the application. If you're using this for your own purposes, you will need to replace values for `account_id`, `route`, etc. for the application to work correctly along with your own [Cloudflare API tokens](https://developers.cloudflare.com/api/resources/accounts/subresources/tokens/methods/create/).\n\nCrucially, you must provide a publicly-accessible BigDipper GraphQL endpoint using the environment variable `GRAPHQL_API` in the `wrangler.toml` file.\n\n### Local Development\n\nWrangler CLI can serve a preview where the code and KV pairs are served from Cloudflare. This also automatically executes a build to be able to serve up the app.\n\n```bash\nwrangler dev\n```\n\nThis option will bind itself to the `preview_id` KV namespace binding (if defined).\n\nWrangler CLI also allows a degree of local development by running the web framework locally, but this option still relies on Cloudflare backend for aspects such as Cloudflare Workers KV.\n\n```bash\nwrangler dev --local\n```\n\nIf you want *completely* standalone local development, this can achieved using an emulator framework like [Miniflare](https://miniflare.dev/).\n\n### Deploy\n\nModify the required variables in `wrangler.toml` for [publishing to Cloudflare Workers](https://developers.cloudflare.com/workers/wrangler/commands/) and execute the following command to execute a build and production deployment.\n\n```bash\nwrangler publish\n```\n\nOther environments can be targetted (if defined in `wrangler.toml`) by specifying the `--env` flag:\n\n```bash\nwrangler publish --env staging\n```\n\nCI/CD deployments can be achieved using the [`wrangler` Github Action](https://github.com/cloudflare/wrangler-action). The [`deploy.yml` Github Action in this repo](https://github.com/cheqd/validator-status/blob/main/.github/workflows/deploy.yml) provides an example of this can be achieved in practice.\n\n## 🐞 Bug reports \u0026 🤔 feature requests\n\nIf you notice anything not behaving how you expected, or would like to make a suggestion / request for a new feature, please create a [**new issue**](https://github.com/cheqd/validator-status/issues/new/choose) and let us know.\n\n## 💬 Community\n\nThe [**cheqd Community Slack**](http://cheqd.link/join-cheqd-slack) is our primary chat channel for the open-source community, software developers, and node operators.\n\nPlease reach out to us there for discussions, help, and feedback on the project.\n\n## 🙋 Find us elsewhere\n\n[![Telegram](https://img.shields.io/badge/Telegram-2CA5E0?style=for-the-badge\u0026logo=telegram\u0026logoColor=white)](https://t.me/cheqd) [![Discord](https://img.shields.io/badge/Discord-7289DA?style=for-the-badge\u0026logo=discord\u0026logoColor=white)](http://cheqd.link/discord-github) [![Twitter](https://img.shields.io/badge/Twitter-1DA1F2?style=for-the-badge\u0026logo=twitter\u0026logoColor=white)](https://twitter.com/intent/follow?screen_name=cheqd_io) [![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge\u0026logo=linkedin\u0026logoColor=white)](http://cheqd.link/linkedin) [![Slack](https://img.shields.io/badge/Slack-4A154B?style=for-the-badge\u0026logo=slack\u0026logoColor=white)](http://cheqd.link/join-cheqd-slack) [![Medium](https://img.shields.io/badge/Medium-12100E?style=for-the-badge\u0026logo=medium\u0026logoColor=white)](https://blog.cheqd.io) [![YouTube](https://img.shields.io/badge/YouTube-FF0000?style=for-the-badge\u0026logo=youtube\u0026logoColor=white)](https://www.youtube.com/channel/UCBUGvvH6t3BAYo5u41hJPzw/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheqd%2Fvalidator-status","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcheqd%2Fvalidator-status","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheqd%2Fvalidator-status/lists"}