feat: implement governance vote monitoring service (#148)

src/modules/governance/votes/alerts/alert-generator.util.ts

@@ -0,0 +1,132 @@
+import { VoteOutcome, ProposalImpact, AlertSeverity } from '../enums';
+
+export interface AlertData {
+  proposalId: string;
+  chainId: number;
+  proposalTitle: string;
+  alertType: string;
+  severity: AlertSeverity;
+  outcome?: string;
+  message: string;
+  proposalLink?: string;
+  network?: string;
+  metadata?: Record<string, unknown>;
+  impact?: ProposalImpact;
+}
+
+const OUTCOME_ALERT_MAP: Record<VoteOutcome, (data: AlertData) => AlertData | null> = {
+  [VoteOutcome.Passed]: data => ({
+    ...data,
+    alertType: 'PROPOSAL_PASSED',
+    severity:
+      data.impact === ProposalImpact.SecurityRelated ? AlertSeverity.Critical : AlertSeverity.High,
+    outcome: VoteOutcome.Passed,
+    message: `Proposal "${data.proposalTitle}" has passed voting`,
+  }),
+  [VoteOutcome.Rejected]: data => ({
+    ...data,
+    alertType: 'PROPOSAL_REJECTED',
+    severity: AlertSeverity.Medium,
+    outcome: VoteOutcome.Rejected,
+    message: `Proposal "${data.proposalTitle}" has been rejected`,
+  }),
+  [VoteOutcome.Executed]: data => ({
+    ...data,
+    alertType: 'PROPOSAL_EXECUTED',
+    severity:
+      data.impact === ProposalImpact.SecurityRelated ? AlertSeverity.Critical : AlertSeverity.High,
+    outcome: VoteOutcome.Executed,
+    message: `Proposal "${data.proposalTitle}" has been executed`,
+  }),
+  [VoteOutcome.Expired]: data => ({
+    ...data,
+    alertType: 'PROPOSAL_EXPIRED',
+    severity: AlertSeverity.Low,
+    outcome: VoteOutcome.Expired,
+    message: `Proposal "${data.proposalTitle}" has expired without execution`,
+  }),
+  [VoteOutcome.Cancelled]: data => ({
+    ...data,
+    alertType: 'PROPOSAL_CANCELLED',
+    severity: AlertSeverity.Low,
+    outcome: VoteOutcome.Cancelled,
+    message: `Proposal "${data.proposalTitle}" has been cancelled`,
+  }),
+  [VoteOutcome.Pending]: () => null,
+};
+
+const IMPACT_ALERT_MAP: Record<ProposalImpact, AlertSeverity> = {
+  [ProposalImpact.ProtocolUpgrade]: AlertSeverity.High,
+  [ProposalImpact.ValidatorChange]: AlertSeverity.High,
+  [ProposalImpact.TreasuryChange]: AlertSeverity.Medium,
+  [ProposalImpact.GovernanceParameterChange]: AlertSeverity.Medium,
+  [ProposalImpact.ContractMigration]: AlertSeverity.High,
+  [ProposalImpact.SecurityRelated]: AlertSeverity.Critical,
+  [ProposalImpact.LowImpact]: AlertSeverity.Low,
+};
+
+export function generateAlertForOutcome(
+  proposalId: string,
+  chainId: number,
+  proposalTitle: string,
+  outcome: VoteOutcome,
+  impact: ProposalImpact,
+  proposalLink?: string,
+  network?: string,
+): AlertData | null {
+  const baseData: AlertData = {
+    proposalId,
+    chainId,
+    proposalTitle,
+    alertType: '',
+    severity: AlertSeverity.Info,
+    outcome,
+    message: '',
+    proposalLink,
+    network,
+    metadata: { impact },
+  };
+
+  const alertGenerator = OUTCOME_ALERT_MAP[outcome];
+  if (!alertGenerator) {
+    return null;
+  }
+
+  const alertData = alertGenerator(baseData);
+  if (!alertData) {
+    return null;
+  }
+
+  alertData.severity = IMPACT_ALERT_MAP[impact] || alertData.severity;
+
+  if (impact === ProposalImpact.SecurityRelated && outcome === VoteOutcome.Passed) {
+    alertData.alertType = 'EMERGENCY_PROPOSAL_APPROVED';
+    alertData.message = `EMERGENCY: Security-related proposal "${proposalTitle}" has been approved`;
+  }
+
+  if (impact === ProposalImpact.ProtocolUpgrade && outcome === VoteOutcome.Passed) {
+    alertData.alertType = 'HIGH_IMPACT_PROTOCOL_UPGRADE';
+    alertData.message = `HIGH IMPACT: Protocol upgrade proposal "${proposalTitle}" has been approved`;
+  }
+
+  if (impact === ProposalImpact.TreasuryChange && outcome === VoteOutcome.Passed) {
+    alertData.alertType = 'TREASURY_PROPOSAL_APPROVED';
+    alertData.message = `Treasury proposal "${proposalTitle}" has been approved`;
+  }
+
+  return alertData;
+}
+
+export function getNetworkName(chainId: number): string {
+  const networkMap: Record<number, string> = {
+    1: 'Ethereum Mainnet',
+    10: 'Optimism',
+    56: 'BSC',
+    137: 'Polygon',
+    250: 'Fantom',
+    42161: 'Arbitrum',
+    43114: 'Avalanche',
+  };
+
+  return networkMap[chainId] || `Chain ${chainId}`;
+}

src/modules/governance/votes/alerts/index.ts

@@ -0,0 +1 @@
+export * from './alert-generator.util';

src/modules/governance/votes/dto/create-vote-alert.dto.ts

@@ -0,0 +1,14 @@
+import { AlertSeverity } from '../enums/alert-severity.enum';
+
+export class CreateVoteAlertDto {
+  proposalId!: string;
+  chainId!: number;
+  proposalTitle!: string;
+  alertType!: string;
+  severity?: AlertSeverity;
+  outcome?: string;
+  message!: string;
+  proposalLink?: string;
+  network?: string;
+  metadata?: Record<string, unknown>;
+}

src/modules/governance/votes/dto/create-vote-outcome.dto.ts

@@ -0,0 +1,25 @@
+import { VoteOutcome } from '../enums/vote-outcome.enum';
+import { ProposalType } from '../enums/proposal-type.enum';
+import { ProposalImpact } from '../enums/proposal-impact.enum';
+
+export class CreateVoteOutcomeDto {
+  proposalId!: string;
+  chainId!: number;
+  proposalTitle!: string;
+  proposalDescription?: string;
+  proposalType?: ProposalType;
+  proposalImpact?: ProposalImpact;
+  outcome?: VoteOutcome;
+  votingStartTime!: Date;
+  votingEndTime!: Date;
+  votingEndedAt?: Date;
+  executionTimestamp?: Date;
+  totalVotes?: string;
+  yesVotes?: string;
+  noVotes?: string;
+  abstainVotes?: string;
+  vetoVotes?: string;
+  participationPercentage?: number;
+  proposalLink?: string;
+  previousState?: string;
+}

src/modules/governance/votes/dto/index.ts

@@ -0,0 +1,4 @@
+export * from './create-vote-outcome.dto';
+export * from './update-vote-outcome.dto';
+export * from './vote-outcome-query.dto';
+export * from './create-vote-alert.dto';

src/modules/governance/votes/dto/update-vote-outcome.dto.ts

@@ -0,0 +1,19 @@
+import { VoteOutcome } from '../enums/vote-outcome.enum';
+import { ProposalType } from '../enums/proposal-type.enum';
+import { ProposalImpact } from '../enums/proposal-impact.enum';
+
+export class UpdateVoteOutcomeDto {
+  outcome?: VoteOutcome;
+  votingEndedAt?: Date;
+  executionTimestamp?: Date;
+  totalVotes?: string;
+  yesVotes?: string;
+  noVotes?: string;
+  abstainVotes?: string;
+  vetoVotes?: string;
+  participationPercentage?: number;
+  proposalType?: ProposalType;
+  proposalImpact?: ProposalImpact;
+  processed?: boolean;
+  previousState?: string;
+}

src/modules/governance/votes/dto/vote-outcome-query.dto.ts

@@ -0,0 +1,16 @@
+import { VoteOutcome } from '../enums/vote-outcome.enum';
+import { ProposalType } from '../enums/proposal-type.enum';
+import { ProposalImpact } from '../enums/proposal-impact.enum';
+
+export class VoteOutcomeQueryDto {
+  chainId?: number;
+  proposalId?: string;
+  outcome?: VoteOutcome;
+  proposalType?: ProposalType;
+  proposalImpact?: ProposalImpact;
+  fromVotingEndedAt?: Date;
+  toVotingEndedAt?: Date;
+  processed?: boolean;
+  limit?: number;
+  offset?: number;
+}

src/modules/governance/votes/entities/vote-alert.entity.ts

@@ -0,0 +1,55 @@
+import { Entity, PrimaryGeneratedColumn, Column, Index, CreateDateColumn } from 'typeorm';
+import { AlertSeverity } from '../enums/alert-severity.enum';
+
+@Entity('governance_vote_alerts')
+@Index(['proposalId', 'chainId'])
+@Index(['chainId', 'severity'])
+@Index(['alertType'])
+@Index(['createdAt'])
+export class VoteAlertEntity {
+  @PrimaryGeneratedColumn('uuid')
+  id!: string;
+
+  @Column({ name: 'proposal_id' })
+  proposalId!: string;
+
+  @Column({ name: 'chain_id' })
+  chainId!: number;
+
+  @Column({ name: 'proposal_title' })
+  proposalTitle!: string;
+
+  @Column({ name: 'alert_type' })
+  alertType!: string;
+
+  @Column({
+    type: 'varchar',
+    enum: AlertSeverity,
+    default: AlertSeverity.Info,
+  })
+  severity!: AlertSeverity;
+
+  @Column({ name: 'outcome', nullable: true })
+  outcome?: string;
+
+  @Column({ name: 'message', type: 'text' })
+  message!: string;
+
+  @Column({ name: 'proposal_link', nullable: true })
+  proposalLink?: string;
+
+  @Column({ name: 'network', nullable: true })
+  network?: string;
+
+  @Column({ name: 'notified', type: 'boolean', default: false })
+  notified!: boolean;
+
+  @Column({ name: 'notification_sent_at', type: 'timestamp', nullable: true })
+  notificationSentAt?: Date;
+
+  @Column({ type: 'simple-json', nullable: true })
+  metadata?: Record<string, unknown>;
+
+  @CreateDateColumn({ name: 'created_at' })
+  createdAt!: Date;
+}

src/modules/governance/votes/entities/vote-outcome.entity.ts

@@ -0,0 +1,106 @@
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  Index,
+  CreateDateColumn,
+  UpdateDateColumn,
+} from 'typeorm';
+import { VoteOutcome } from '../enums/vote-outcome.enum';
+import { ProposalType } from '../enums/proposal-type.enum';
+import { ProposalImpact } from '../enums/proposal-impact.enum';
+
+@Entity('governance_vote_outcomes')
+@Index(['proposalId', 'chainId'], { unique: true })
+@Index(['chainId', 'outcome'])
+@Index(['chainId', 'votingEndedAt'])
+@Index(['proposalType'])
+@Index(['proposalImpact'])
+export class VoteOutcomeEntity {
+  @PrimaryGeneratedColumn('uuid')
+  id!: string;
+
+  @Column({ name: 'proposal_id' })
+  proposalId!: string;
+
+  @Column({ name: 'chain_id' })
+  chainId!: number;
+
+  @Column({ name: 'proposal_title' })
+  proposalTitle!: string;
+
+  @Column({ name: 'proposal_description', type: 'text', nullable: true })
+  proposalDescription?: string;
+
+  @Column({
+    type: 'varchar',
+    enum: ProposalType,
+    default: ProposalType.Other,
+  })
+  proposalType!: ProposalType;
+
+  @Column({
+    type: 'varchar',
+    enum: ProposalImpact,
+    default: ProposalImpact.LowImpact,
+  })
+  proposalImpact!: ProposalImpact;
+
+  @Column({
+    type: 'varchar',
+    enum: VoteOutcome,
+    default: VoteOutcome.Pending,
+  })
+  outcome!: VoteOutcome;
+
+  @Column({ name: 'voting_start_time', type: 'timestamp' })
+  votingStartTime!: Date;
+
+  @Column({ name: 'voting_end_time', type: 'timestamp' })
+  votingEndTime!: Date;
+
+  @Column({ name: 'voting_ended_at', type: 'timestamp', nullable: true })
+  votingEndedAt?: Date;
+
+  @Column({ name: 'execution_timestamp', type: 'timestamp', nullable: true })
+  executionTimestamp?: Date;
+
+  @Column({ name: 'total_votes', default: '0' })
+  totalVotes!: string;
+
+  @Column({ name: 'yes_votes', default: '0' })
+  yesVotes!: string;
+
+  @Column({ name: 'no_votes', default: '0' })
+  noVotes!: string;
+
+  @Column({ name: 'abstain_votes', default: '0' })
+  abstainVotes!: string;
+
+  @Column({ name: 'veto_votes', default: '0' })
+  vetoVotes!: string;
+
+  @Column({
+    name: 'participation_percentage',
+    type: 'decimal',
+    precision: 5,
+    scale: 2,
+    nullable: true,
+  })
+  participationPercentage?: number;
+
+  @Column({ name: 'proposal_link', nullable: true })
+  proposalLink?: string;
+
+  @Column({ name: 'previous_state', nullable: true })
+  previousState?: string;
+
+  @Column({ name: 'processed', type: 'boolean', default: false })
+  processed!: boolean;
+
+  @CreateDateColumn({ name: 'created_at' })
+  createdAt!: Date;
+
+  @UpdateDateColumn({ name: 'updated_at' })
+  updatedAt!: Date;
+}

src/modules/governance/votes/enums/alert-severity.enum.ts

@@ -0,0 +1,7 @@
+export enum AlertSeverity {
+  Critical = 'CRITICAL',
+  High = 'HIGH',
+  Medium = 'MEDIUM',
+  Low = 'LOW',
+  Info = 'INFO',
+}

src/modules/governance/votes/enums/index.ts

@@ -0,0 +1,5 @@
+export * from './vote-outcome.enum';
+export * from './vote-status.enum';
+export * from './proposal-type.enum';
+export * from './alert-severity.enum';
+export * from './proposal-impact.enum';