PolGuard

PolGuard is a modular real-time monitoring platform for Polkadot, Kusama, and parachains. It tracks on-chain activity - balances, staking, governance, identity, assets, and XCM - surfacing what it detects as incidents, with monitoring rules defined in a single YAML config family shared across services.

Quick Start

Prerequisites: Node.js 22+, Yarn 4.11+

git clone https://github.com/w3f/polguard.git
cd polguard
yarn install
yarn build
yarn start:chain

Uses default monitoring configuration from packages/config/examples/, starts from the Asset Hub Polkadot latest finalized block.

Incidents

Everything PolGuard detects is an incident, with two independent properties:

• Lifecycle - one-time (a single occurrence, immediately resolved - e.g. a transfer) or ongoing (fires and later resolves - e.g. a balance dipping below a threshold)
• Response - actionable (a human acknowledges it via the bot, and it escalates to extra channels if they don't) or informational (surfaced for awareness)

Deployment Modes

Standalone Mode

Run the Chain service on its own - for trying it out, integrating via webhooks, or simple deployments. See the Chain service documentation for architecture and configuration.

Platform Mode

Run the full stack - incident management with database persistence and Matrix notifications.

graph LR
    Blockchain[("RPC node")]:::blockchain
    Postgres[(PostgreSQL)]:::database
    MatrixExt["Matrix<br>(Server & Rooms)"]:::external
    Config["<a href='https://github.com/w3f/polguard/blob/main/packages/config/CONFIG_GUIDE.md' title='Configuration Guide'>Monitoring Config</a><br>(YAML files)"]:::config

    subgraph Services ["PolGuard"]
        Incident["<a href='https://github.com/w3f/polguard/blob/main/packages/incident/README.md' title='Incident Service Documentation'>Incident Service</a><br>Incident & state management"]:::service
        Matrix["<a href='https://github.com/w3f/polguard/blob/main/packages/matrix/README.md' title='Matrix Service Documentation'>Matrix Service</a><br>Notifications & bot"]:::service
        Chain["<a href='https://github.com/w3f/polguard/blob/main/packages/chain/README.md' title='Chain Service Documentation'>Chain Service</a><br>Blockchain monitor"]:::service
    end

    Chain -->|"Subscribes to blocks,<br>queries state"| Blockchain
    Chain -.->|"Reads rules"| Config
    Chain -->|"Creates/resolves<br>incidents"| Incident
    Incident -->|"Sends<br>notifications"| Matrix
    Matrix -->|"Acks, queries,<br>resolves incidents"| Incident
    Matrix <-->|"Sends messages,<br>receives commands"| MatrixExt
    Incident -->|"Persists data"| Postgres

    classDef service fill:#FFF2CC,stroke:#D6B656,stroke-width:2px
    classDef blockchain fill:#E1D5E7,stroke:#9673A6,stroke-width:2px
    classDef database fill:#D4E8D4,stroke:#82B366,stroke-width:2px
    classDef external fill:#F5F5F5,stroke:#666666,stroke-width:2px
    classDef config fill:#F8CECC,stroke:#B85450,stroke-width:1px

Loading

# After cloning, installing, and building (Quick Start), start services in order:
yarn start:incident
yarn start:matrix
yarn start:chain

Setup requirements:

• PostgreSQL database for the Incident service
• Service config files for each service (examples in packages/*/config/)
• Matrix server credentials

Monitoring Configuration

Monitoring rules - what to watch and how to report it - are written in YAML, separately from each service's own runtime config (RPC endpoint, store, reporters, etc.). By default the Chain service loads the example rules in packages/config/examples/. To define your own:

• Write YAML rules following the Config Guide
• Point monitoringConfigsDir in the Chain service config at your directory

See Monitors & Handlers for everything that can be monitored. The same files also enroll accounts for the optional Payouts service - see Operations: Payouts.

Documentation

Core Services

• Chain Service - Blockchain monitoring service
• Incident Service - REST API for incident & last block management
• Matrix Service - Notifications & bot service
• Payouts Service - Optional operations component: automated validator reward claims

Supporting Packages

• Common Package - Shared types, constants, utilities and telemetry
• Config Package - YAML monitoring config & validation

Configuration & Monitoring

• Config Guide - Monitoring rules configuration
• Monitors & Handlers - List of all supported monitors and handlers

Development & Operations

• Deployment Guide - Docker images, Helm chart, CI & npm publishing
• E2E Tests - End-to-end testing setup and execution

Contributing

PolGuard is built and maintained by the Web3 Foundation SecOps team for our own monitoring needs. See CONTRIBUTING.md for what that means for issues and pull requests, and SECURITY.md for reporting vulnerabilities privately.