💚 Implement Protocol Health Monitoring
Issue: #152
Type: Feature
Priority: High
Estimated Effort: 2–4 days
🧠 Concept
Implement a Protocol Health Monitoring service that continuously evaluates the operational health of monitored blockchain protocols and smart contract systems. The service should collect key health metrics, detect abnormal behavior, evaluate configurable health thresholds, and generate alerts when protocol conditions indicate potential security, operational, or availability risks.
The monitoring system should provide an early warning mechanism for protocol degradation before it escalates into outages, exploits, or user-facing incidents.
⚠️ Problem
Security incidents are often preceded by changes in protocol behavior, such as declining transaction throughput, spikes in failed transactions, unexpected contract activity, or network instability.
Currently, there is no centralized mechanism to continuously assess protocol health or identify operational anomalies.
Without protocol health monitoring:
- Performance degradation may go unnoticed until users are affected.
- Security teams lose valuable early indicators of attacks or exploits.
- Protocol outages are detected too late.
- Operational metrics cannot be correlated with security incidents.
- Long-term health trends are unavailable for analysis.
📁 Implementation Scope
src/modules/protocols/health/
Suggested structure:
health/
├── protocol-health.service.ts
├── health-monitor.service.ts
├── metrics-collector.service.ts
├── health-evaluator.service.ts
├── threshold-engine.service.ts
├── protocol-health.repository.ts
├── dto/
├── entities/
├── interfaces/
├── enums/
├── alerts/
└── utils/
✅ Requirements
Protocol Registration
Support monitoring one or more configured protocols.
Each monitored protocol should include configurable metadata such as:
- Protocol name
- Network
- Version (optional)
- Monitored contracts
- Monitoring interval
- Enabled/disabled status
The design should support onboarding additional protocols with minimal configuration changes.
Health Metrics Collection
Continuously collect operational metrics for monitored protocols.
Example metrics include:
- Transaction throughput (TPS)
- Transaction success rate
- Failed transaction rate
- Contract invocation frequency
- Event emission rate
- Block processing rate
- Active user/account count
- Gas or fee consumption (where applicable)
- Average transaction confirmation time
- RPC/API availability
- Contract execution failures
Metrics should be timestamped and persisted for historical analysis.
Activity Monitoring
Monitor protocol activity for abnormal behavior, including:
- Sudden spikes in transaction volume
- Sharp declines in protocol activity
- Large increases in failed transactions
- Unexpected contract interaction patterns
- Significant reductions in active users
- Prolonged inactivity
- Repeated execution failures
- Unusual event generation rates
The monitoring engine should support configurable observation windows for short-term and long-term analysis.
Health Evaluation Engine
Implement a health evaluation engine that derives an overall protocol health status from collected metrics.
Example health states:
- Healthy
- Degraded
- Warning
- Critical
- Offline
Health evaluations should consider multiple metrics together rather than relying on a single threshold.
Threshold Monitoring
Support configurable thresholds for individual health metrics.
Example thresholds:
- Failed transaction rate exceeds 15%
- TPS falls below configured baseline
- API availability below 99%
- Contract execution failures exceed threshold
- Confirmation time exceeds acceptable limits
- Activity drops by more than a configured percentage
Thresholds should be configurable per protocol rather than globally hardcoded.
Historical Health Tracking
Persist protocol health snapshots including:
- Timestamp
- Health status
- Individual metric values
- Threshold evaluation results
- Overall health score (if applicable)
Historical records should support dashboards, reporting, audits, and incident investigations.
Alert Generation
Generate alerts when:
- Health thresholds are exceeded
- Protocol health status changes
- Metrics deteriorate rapidly
- A protocol becomes unavailable
- Activity deviates significantly from historical baselines
Alerts should include:
- Protocol name
- Network
- Triggering metric(s)
- Observed value
- Configured threshold
- Health status
- Severity
- Timestamp
Alerts should integrate with the platform's existing notification and incident management pipeline.
Trend Analysis
Support trend calculations for:
- Health score over time
- Metric history
- Performance degradation
- Recovery trends
- Threshold breach frequency
- Protocol availability
These trends should be optimized for frontend dashboards and reporting.
Error Handling
The monitoring service should:
- Retry transient failures
- Continue monitoring remaining protocols if one collector fails
- Log collection and evaluation errors with sufficient context
- Gracefully handle temporary RPC or API outages
🔒 Non-Functional Requirements
- Configurable monitoring intervals
- Modular metrics collection architecture
- Extensible health evaluation engine
- Idempotent metric processing
- Efficient storage for historical metrics
- Structured logging
- Type-safe DTOs and entities
- Unit-testable monitoring logic
- Scalable architecture supporting multiple protocols concurrently
🎯 Acceptance Criteria
💚 Implement Protocol Health Monitoring
Issue: #152
Type: Feature
Priority: High
Estimated Effort: 2–4 days
🧠 Concept
Implement a Protocol Health Monitoring service that continuously evaluates the operational health of monitored blockchain protocols and smart contract systems. The service should collect key health metrics, detect abnormal behavior, evaluate configurable health thresholds, and generate alerts when protocol conditions indicate potential security, operational, or availability risks.
The monitoring system should provide an early warning mechanism for protocol degradation before it escalates into outages, exploits, or user-facing incidents.
Security incidents are often preceded by changes in protocol behavior, such as declining transaction throughput, spikes in failed transactions, unexpected contract activity, or network instability.
Currently, there is no centralized mechanism to continuously assess protocol health or identify operational anomalies.
Without protocol health monitoring:
📁 Implementation Scope
Suggested structure:
✅ Requirements
Protocol Registration
Support monitoring one or more configured protocols.
Each monitored protocol should include configurable metadata such as:
The design should support onboarding additional protocols with minimal configuration changes.
Health Metrics Collection
Continuously collect operational metrics for monitored protocols.
Example metrics include:
Metrics should be timestamped and persisted for historical analysis.
Activity Monitoring
Monitor protocol activity for abnormal behavior, including:
The monitoring engine should support configurable observation windows for short-term and long-term analysis.
Health Evaluation Engine
Implement a health evaluation engine that derives an overall protocol health status from collected metrics.
Example health states:
Health evaluations should consider multiple metrics together rather than relying on a single threshold.
Threshold Monitoring
Support configurable thresholds for individual health metrics.
Example thresholds:
Thresholds should be configurable per protocol rather than globally hardcoded.
Historical Health Tracking
Persist protocol health snapshots including:
Historical records should support dashboards, reporting, audits, and incident investigations.
Alert Generation
Generate alerts when:
Alerts should include:
Alerts should integrate with the platform's existing notification and incident management pipeline.
Trend Analysis
Support trend calculations for:
These trends should be optimized for frontend dashboards and reporting.
Error Handling
The monitoring service should:
🔒 Non-Functional Requirements
🎯 Acceptance Criteria