OpenZeppelin Monitor

In the rapidly evolving world of blockchain technology, effective monitoring is crucial for ensuring security and performance. OpenZeppelin Monitor is a blockchain monitoring service that watches for specific on-chain activities and triggers notifications based on configurable conditions. The service offers multi-chain support with configurable monitoring schedules, flexible trigger conditions, and an extensible architecture for adding new chains.

Install | User Docs | Quickstart | Crate Docs

Features

• Real-time Monitoring: Watch blockchain networks in real-time for specific events and transactions
• Smart Filtering: Use flexible expressions to define exactly what you want to monitor
• Multi-notification Support: Send alerts via Slack, Discord, Email, Telegram, Webhooks, or custom scripts
• Configurable Scheduling: Set custom monitoring schedules using cron expressions
• Data Persistence: Store monitoring data and resume from checkpoints
• Missed Block Recovery: Automatically retry fetching and processing blocks that were missed due to RPC failures
• Extensible Architecture: Easy to add support for new blockchains and notification types

Supported Networks

• EVM-Compatible Networks
• Stellar
• Solana
• Midnight (Partially Supported)

Notification Channels

• Slack - Send formatted messages to Slack channels
• Discord - Post alerts to Discord channels via webhooks
• Email - Send email notifications with SMTP support
• Telegram - Send messages to Telegram chats via bot API
• Webhooks - Send HTTP requests to custom endpoints
• Custom Scripts - Execute Python, JavaScript, or Bash scripts

For Users

Installation

• View the Installation documentation for detailed information. For a quicker introduction, check out the Quickstart guide.

• Prerequisites: Copy example configuration files to ./config directory and modify according to your needs. See examples for more information.

Running the Monitor

View the Running the Monitor documentation for more information.

For Developers

Technical Overview

The following diagram illustrates the architecture of the monitoring service, highlighting key components and their interactions.

graph TD
subgraph Entry Point
MAIN[main.rs]
end

    subgraph Bootstrap
        BOOTSTRAP[Bootstrap::initialize_service]
    end

    subgraph Block Processing
        BT[BlockTracker]
        BS[BlockStorage]
        BWS[BlockWatcherService]
        BH[create_block_handler]
        BR[BlockRecovery]
    end

    subgraph Core Services
        MS[MonitorService]
        NS[NetworkService]
        TS[TriggerService]
        FS[FilterService]
        TES[TriggerExecutionService]
        NOTS[NotificationService]
    end

    subgraph Client Layer
        CP[ClientPool]
        EVMC[EVMClient]
        SC[StellarClient]
        SOC[SolanaClient]
        MC[MidnightClient]
    end

    %% Initialization Flow
    MAIN --> BOOTSTRAP
    BOOTSTRAP --> CP
    BOOTSTRAP --> NS
    BOOTSTRAP --> MS
    BOOTSTRAP --> TS
    BOOTSTRAP --> FS
    BOOTSTRAP --> TES
    BOOTSTRAP --> NOTS

    %% Block Processing Setup
    BOOTSTRAP --> BT
    BOOTSTRAP --> BS
    BOOTSTRAP --> BWS
    BOOTSTRAP --> BH

    %% Client Dependencies
    CP --> EVMC
    CP --> SC
    CP --> SOC
    CP --> MC
    BWS --> CP

    %% Service Dependencies
    BWS --> BS
    BWS --> BT
    MS --> NS
    MS --> TS
    FS --> TES
    TES --> NOTS

    %% Block Handler Connection
    BH --> FS
    BWS --> BH

    %% Recovery Connection
    BWS --> BR
    BR --> BS
    BR --> CP

    style MAIN fill:#e1f5fe,stroke:#01579b,color:#333333
    style BOOTSTRAP fill:#fff3e0,stroke:#ef6c00,color:#333333
    classDef blockProcessing fill:#e8f5e9,stroke:#2e7d32,color:#333333
    classDef coreServices fill:#f3e5f5,stroke:#7b1fa2,color:#333333
    classDef clients fill:#fce4ec,stroke:#c2185b,color:#333333

    class BT,BS,BWS,BH,BR blockProcessing
    class MS,NS,TS,FS,TES,NOTS coreServices
    class CP,EVMC,SC,SOC,MC clients

Project Structure

openzeppelin-monitor/
├── src/                # Source code
│   ├── bootstrap/      # Bootstrap functions for the application
│   ├── models/         # Data structures and types
│   ├── repositories/   # Configuration storage
│   ├── services/       # Core business logic
│   ├── utils/          # Helper functions
│
├── config/             # Configuration files
├── tests/              # Integration and property-based tests
├── data/               # Runtime data storage
├── docs/               # Documentation
├── scripts/            # Utility scripts
├── cmd/                # Metrics and monitoring
├── examples/           # Example configuration files
└── ... other root files (Cargo.toml, README.md, etc.)

Development Environment Setup

System Dependencies (Linux)

To get started on Ubuntu 22.04+ or Debian-based systems (both x86 and ARM64 architectures):

Note: Python 3.9+ is required for pre-commit hooks compatibility.

# Install required packages directly
sudo apt update
sudo apt install -y \
    build-essential \
    curl \
    git \
    pkg-config \
    libssl-dev \
    libffi-dev \
    libyaml-dev \
    python3 \
    python3-venv \
    python3-pip

or run the linux system package script (automatically ensures Python 3.9+ compatibility):

chmod +x ./scripts/linux/sys_pkgs_core.sh
chmod +x ./scripts/linux/sys_pkgs_dev.sh
# Installs required packages and ensures compatible Python version
./scripts/linux/sys_pkgs_core.sh   # For runtime dependencies only
./scripts/linux/sys_pkgs_dev.sh    # For Python/dev dependencies (calls core script)

Prerequisites

• Rust 2024 edition, version 1.90 or later.
• Git for version control
• Python/pip for pre-commit hooks

Initial Setup

# Clone the repository
git clone https://github.com/openzeppelin/openzeppelin-monitor
cd openzeppelin-monitor

# Build the project
cargo build

# Set up environment variables
cp .env.example .env

Install Pre-commit Hooks

Required for code quality checks including rustfmt, clippy, and commit message validation.

# Install pre-commit (use pipx for global installation if preferred)
pip install pre-commit

# Install and configure hooks for commit-msg, pre-commit, and pre-push
pre-commit install --install-hooks -t commit-msg -t pre-commit -t pre-push

:warning: If you encounter issues with pip, consider using pipx for a global installation.

Install Rust Toolchain Components

rustup component add rustfmt

Running Tests

To run tests, use the following commands:

RUST_TEST_THREADS=1 cargo test
RUST_TEST_THREADS=1 cargo test properties
RUST_TEST_THREADS=1 cargo test integration

Generate Test Coverage Report

Interactive HTML Report

RUST_TEST_THREADS=1 cargo +stable llvm-cov --html --open

CLI Report

RUST_TEST_THREADS=1 cargo +stable llvm-cov

Important Considerations

Performance Considerations

• Monitor performance depends on network congestion and RPC endpoint reliability.
• The max_past_blocks configuration is critical:
• Calculate as: (cron_interval_ms/block_time_ms) + confirmation_blocks + 1 (defaults to this calculation if not specified).
• Example for 1-minute Ethereum cron: (60000/12000) + 12 + 1 = 18 blocks.
• Too low settings may result in missed blocks.
• Trigger conditions are executed sequentially based on their position in the trigger conditions array. Proper execution also depends on the number of available file descriptors on your system. Ideally, you should increase the open file descriptor limit to at least 2,048 or higher for optimal performance.
• Security Risk: Only run scripts that you trust and fully understand. Malicious scripts can harm your system or expose sensitive data. Always review script contents and verify their source before execution.
• HTTP requests to RPC endpoints may consume file descriptors for each connection. The number of concurrent connections can increase significantly when processing blocks with many transactions, as each transaction may require multiple RPC calls.

Missed Block Recovery

When RPC failures or network issues cause blocks to be missed during normal monitoring cycles, the missed block recovery feature can automatically retry fetching and processing them. This runs as a separate background job to avoid impacting the main monitoring loop.

To enable recovery, add a recovery_config to your network configuration:

{
  "recovery_config": {
    "enabled": true,
    "cron_schedule": "0 */5 * * * *",
    "max_blocks_per_run": 10,
    "max_block_age": 1000,
    "max_retries": 3,
    "retry_delay_ms": 1000
  }
}

Configuration options: - enabled - Whether the recovery job is active - cron_schedule - When to run recovery (separate from main monitor schedule) - max_blocks_per_run - Maximum blocks to attempt per recovery cycle (limits RPC load) - max_block_age - Blocks older than this (in blocks from current) are pruned and not recovered - max_retries - Maximum retry attempts before marking a block as failed - retry_delay_ms - Delay between retry attempts

See the example network configurations in examples/config/networks/ for recommended settings per chain.

Notification Considerations

• Email notification port defaults to 465 if not specified.
• Template variables are context-dependent:
• Event-triggered notifications only populate event variables.
• Function-triggered notifications only populate function variables.
• Mixing contexts results in empty values.

Contributing

We welcome contributions from the community! Before contributing, please note these requirements:

Key Requirements

• Contributor License Agreement (CLA): All contributors must sign the CLA before contributing
• Signed Commits: All commits must be GPG-signed for security
• Pre-commit hooks: Required for code quality checks including rustfmt, clippy, and commit message validation

Getting Started

1. Fork the repository
2. Clone your fork and set up development environment
3. Install pre-commit hooks
4. Create your feature branch
5. Make your changes with proper testing
6. Submit a Pull Request

If you are looking for a good place to start, find a good first issue here.

You can open an issue for a bug report, feature request, or documentation request.

For complete details including GitHub workflow, labeling guidelines, and advanced topics, see our Contributing guide. For the full contribution workflow and standards, see also the Contribution guidelines on the docs site.

Please read our Code of Conduct and check the Security Policy for reporting vulnerabilities.

License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.

Security

For security concerns, please refer to our Security Policy.

Get Help

If you have any questions, first see if the answer to your question can be found in the User Documentation.

Community Support

• Telegram: Join our community chat for help and discussions
• GitHub Issues: Open a bug report or feature request
• Good First Issues: Find beginner-friendly issues
• **GitHub