feat: implement governance vote monitoring service (#148)

[jotel-dev]

Description
Problem Statement The Sentinel platform currently lacks automated governance vote monitoring, creating significant operational blind spots. Governance proposals can introduce critical protocol changes (smart contract upgrades, parameter modifications, treasury allocations, validator configurations) that directly impact monitored contracts and system behavior. Without automated tracking:

Critical protocol changes may go unnoticed until after execution
Security teams cannot proactively respond to impactful governance decisions
Analysts must manually monitor multiple governance portals
Historical governance outcomes are unavailable for trend analysis
No alerting mechanism exists for time-sensitive governance events
Proposed Solution This PR implements a comprehensive governance vote monitoring service under votes that:

Continuously tracks proposals across supported governance protocols
Detects voting conclusion and records final outcomes
Generates contextual alerts for significant governance events
Maintains historical governance data for audit and analysis
Provides impact classification for proposal prioritization
Closes #148

🛠️ Technical Implementation Details

1. Vote Monitoring Architecture (GovernanceVoteService)
   Implements a polling-based monitoring system that:

Proposal Discovery: Integrates with existing ProposalDetector to fetch active proposals from Governor contracts
State Transition Detection: Maps Governor Bravo states (Pending → Active → Succeeded/Defeated → Executed) to internal VoteOutcome enum
Vote Aggregation: Retrieves and persists yes/no/abstain/veto vote tallies with participation percentages
Idempotent Processing: Uses database upserts to prevent duplicate processing of completed proposals
Multi-Chain Support: Configurable polling intervals per chain with independent detector instances
2. Outcome Processing & Alerting (GovernanceVoteProcessor)
Processes vote monitoring results and generates contextual alerts:

State Change Detection: Triggers alerts only when proposal outcomes transition (Active → Passed/Rejected)
Impact-Based Severity: Classifies proposals by impact level (Security-Related = Critical, Protocol Upgrade = High, Treasury = Medium)
Alert Types: Generates specific alerts for PROPOSAL_PASSED, PROPOSAL_REJECTED, PROPOSAL_EXECUTED, EMERGENCY_PROPOSAL_APPROVED, HIGH_IMPACT_PROTOCOL_UPGRADE
Vote Update Tracking: Monitors vote count changes even without state transitions
3. Automated Scheduling (GovernanceVoteScheduler)
Provides configurable, resilient monitoring cycles:

Configurable Intervals: Default 60-second polling with per-chain override capability
Graceful Error Handling: Continues monitoring remaining chains if individual requests fail
Lifecycle Management: Clean start/stop with running state tracking
Transient Failure Retry: Logs errors without stopping the monitoring service
4. Proposal Classification (proposal-classifier.util)
Implements keyword-based impact classification:

Protocol Upgrade: upgrade, migration, contract upgrade, implementation
Validator Changes: validator, node operator, staking, slashing
Treasury Changes: treasury, grant, funding, budget, allocation
Security Proposals: security, emergency, pause, unpause, critical
Parameter Changes: parameter, threshold, quorum, timelock, delay
📂 Database Schema Changes
Two new entities with TypeORM decorators:

VoteOutcomeEntity (governance_vote_outcomes)
Stores proposal metadata, voting results, and outcome state
Indexed on proposalId + chainId (unique), chainId + outcome, votingEndedAt
Tracks proposal type, impact classification, and processing status
Persists vote counts (yes/no/abstain/veto) with participation percentages
VoteAlertEntity (governance_vote_alerts)
Stores generated alerts with severity and notification status
Indexed on proposalId + chainId, chainId + severity, alertType
Tracks notification delivery status and timestamps
Supports flexible metadata storage for alert context
📋 Quality Assurance & Testing Matrix
Code Quality Verification
Type Safety: Full TypeScript coverage with strict type definitions
Code Style: Follows existing codebase patterns (service/repository/entity separation)
Linting: Compatible with existing ESLint configuration
Architecture: Aligns with existing governance module structure
Functional Validation Requirements
Component Test Scenario Expected Behavior
Vote Monitoring Active proposal voting concludes State transition detected, outcome persisted
Vote Monitoring Proposal already processed Idempotent upsert, no duplicate records
Alert Generation Security proposal passes Critical severity alert generated
Alert Generation Low-impact proposal rejected Low severity alert generated
Classification Proposal with "upgrade" keyword Classified as ProtocolUpgrade impact
Scheduler Service start/stop Clean lifecycle management
Scheduler Chain request failure Continues monitoring other chains
🚀 Deployment & Migration Strategy
Pre-Deployment Requirements
Ensure TypeORM entities are registered in the data source configuration
Configure governance monitoring parameters (chain IDs, governor addresses, polling intervals)
Set up database indexes for optimal query performance
Database Actions
Run TypeORM migration to create governance_vote_outcomes and governance_vote_alerts tables
Existing tables are not modified - zero breaking changes
New indexes are non-blocking and can be created on live databases
Configuration

typescript
// Example configuration for governance vote monitoring
const governanceConfig: GovernanceVoteConfig[] = [
{
chainId: 1,
governorAddress: '0x...',
pollIntervalMs: 60000,
enabled: true,
networkName: 'Ethereum Mainnet',
proposalLinkTemplate: 'https://snapshot.org/#/proposal/{proposalId}'
}
];
Rollback Plan
Remove governance vote module initialization from application bootstrap
Drop new database tables if persistence cleanup is required
No impact on existing governance proposal detection functionality
Monitoring Integration
The service integrates seamlessly with existing ProposalDetector and ProposalRepository components, requiring no changes to current governance proposal tracking infrastructure.

closes #148

[mijinummi]

Hi @jotel-dev , great work. Thank you for taking part on this. Could you please run npm lint to fix the remaining ci?

[jotel-dev]

I'm coming
still working it

[mijinummi]

Alright great, nice work so far.

[jotel-dev]

Done @mijinummi

[mijinummi]

LGTM!