Setting Up a Governance Notification and Alert System

On-chain governance is a core innovation of decentralized protocols, but staying informed about proposals, votes, and execution is a manual and time-consuming process. A governance notification system automates this by monitoring smart contract events and delivering real-time alerts to your preferred channels—be it Discord, Telegram, or email. This guide walks through building such a system using tools like Chainscore's Governance API, webhook listeners, and serverless functions to track key events from protocols like Uniswap, Compound, or Arbitrum.

The foundation of any alert system is reliable data ingestion. Instead of running your own node, you can use specialized APIs that index and structure governance data. For example, Chainscore's API provides normalized event streams for proposal creation (ProposalCreated), voting (VoteCast), and execution (ProposalExecuted). You can filter these streams by DAO address, proposal ID, or voter address to create targeted subscriptions. Setting up a listener involves configuring a webhook endpoint that will receive POST requests containing the event payload whenever a matching on-chain action occurs.

Once your data pipeline is established, the next step is processing and routing alerts. A simple architecture uses a serverless function (e.g., on Vercel or AWS Lambda) as your webhook receiver. This function parses the incoming JSON, formats a human-readable message, and dispatches it. For Discord, you would use a webhook URL to post to a channel. For Telegram, you interact with the Bot API. The alert should include essential details: the proposal title, a link to the voting interface (like Tally or Snapshot), the current vote tally, and the time remaining.

To make the system robust, implement error handling and status monitoring. Log all received events and failed notifications. Set up a secondary alert (e.g., via PagerDuty or a dedicated channel) to notify you if your primary webhook goes offline. Furthermore, consider adding logic to filter out noise—you might only want alerts for proposals that meet a quorum threshold or are submitted by specific delegate addresses. This ensures you're notified about impactful governance actions without being overwhelmed.

Finally, test your system end-to-end. Many testnets have governance facsimiles, or you can simulate events using forked mainnet environments with tools like Foundry or Hardhat. Deploy your listener, trigger a test proposal on a forked chain, and verify the alert delivers correctly. A well-constructed governance alert system transforms you from a passive observer into an active, informed participant, ensuring you never miss a critical vote or execution deadline that could affect your stakes or the protocols you rely on.

A robust governance alert system requires a reliable data ingestion layer. You will need access to a blockchain node or a node provider service like Alchemy, Infura, or a QuickNode endpoint for the target chain (e.g., Ethereum, Polygon, Arbitrum). For reading on-chain governance data, you must interact with the specific DAO's smart contracts, primarily its governance contract (e.g., a Governor contract from OpenZeppelin) and its token contract. Essential tools include Node.js (v18+) or Python (3.9+), a package manager like npm or pip, and a code editor such as VS Code.

The core architecture follows an event-driven pattern. A listener service (or script) polls the blockchain for new events emitted by the governance contract, such as ProposalCreated, VoteCast, or ProposalExecuted. This service can be built using ethers.js or web3.py libraries. Upon detecting an event, the system processes the data—parsing proposal IDs, voter addresses, and vote power—and formats it into a structured message. This message is then passed to a notification dispatcher.

The dispatcher's role is to deliver alerts through chosen channels. Common integrations include Discord (using webhooks), Telegram (via the Bot API), Twitter/X (using the API v2), and email (with SMTP or services like SendGrid). For production systems, you should implement a queuing mechanism (e.g., Redis or RabbitMQ) to handle message delivery reliably and avoid losing alerts during downstream service outages. A simple database like PostgreSQL or SQLite is also useful for logging sent alerts and preventing duplicate notifications.

Security and cost are critical considerations. Your node provider API key and all bot tokens (Discord, Telegram, etc.) are sensitive credentials that must be stored securely using environment variables or a secrets manager—never hardcode them. If you are running your own listener, be mindful of RPC request costs and potential rate limits; using a WebSocket connection for events is more efficient than polling with HTTP. For systems monitoring multiple DAOs, architecting a modular service that can be easily configured with new contract addresses is essential for scalability.

Governance actions on-chain are triggered by transactions that call specific functions in the protocol's smart contracts. When these functions execute, they often emit events (or logs) that are permanently recorded on the blockchain. These events are your primary data source. For example, a ProposalCreated event contains crucial details like the proposal ID, proposer address, targets, values, and calldata. You must locate the exact contract addresses and the ABI (Application Binary Interface) definitions for the governance module, which is often a separate contract like a Governor or Timelock.

To find these events, start with the protocol's official documentation and verified source code on block explorers like Etherscan or Arbiscan. Look for the contract labeled as the governor (e.g., GovernorBravo, OZ Governor). Within the contract's "Contract" tab, examine the "Events" section. For a Uniswap-style governor, key events typically include ProposalCreated, ProposalQueued, ProposalExecuted, and VoteCast. You will need the exact event signatures and parameter types to decode them later.

Here is a simplified example of what a ProposalCreated event definition looks like in a Solidity interface, which you would need to include in your monitoring script's ABI:

solidityCopy
event ProposalCreated(
    uint256 proposalId,
    address proposer,
    address[] targets,
    uint256[] values,
    string[] signatures,
    bytes[] calldatas,
    uint256 startBlock,
    uint256 endBlock,
    string description
);

This structure tells your indexer what data fields to expect and how to parse them from the raw log data.

After identifying the events, you must determine the correct blockchain and network (e.g., Ethereum Mainnet, Arbitrum, Optimism). Governance contracts are often deployed on Layer 1 but can exist on Layer 2s or sidechains. Note the contract's deployment address and the starting block number from which to begin scanning for historical data. This setup forms the foundation for the next step: connecting to a node and listening for these events in real-time.

An event listener is a script that connects to a blockchain node and subscribes to specific smart contract events. For governance, you'll typically listen for events like ProposalCreated, VoteCast, or ProposalExecuted. Using the ethers.js library, you can create a robust listener that runs continuously. First, install the required packages: npm install ethers dotenv. The dotenv package is used to securely load your RPC URL and contract address from a .env file.

The core of the listener is the ethers.Contract object and its on method. You must instantiate a provider using a WebSocket RPC endpoint (e.g., from Alchemy or Infura), as HTTP providers do not support real-time subscriptions. Then, create a contract instance using the governance contract's ABI and address. Finally, use contract.on("EventName", callback) to define the function that runs when the event is emitted on-chain. This callback receives the event arguments, which you can process and forward to your alert logic.

Here is a basic code structure for listening to a ProposalCreated event:

javascriptCopy
const { ethers } = require('ethers');
require('dotenv').config();

const provider = new ethers.WebSocketProvider(process.env.WS_RPC_URL);
const contract = new ethers.Contract(
  process.env.GOVERNANCE_ADDRESS,
  ["event ProposalCreated(uint256 id, address proposer, address[] targets, uint256[] values, string[] signatures, bytes[] calldatas, uint256 startBlock, uint256 endBlock, string description)"],
  provider
);

contract.on("ProposalCreated", (id, proposer, targets, description, event) => {
  console.log(`New Proposal #${id} by ${proposer}: ${description}`);
  // Add logic to send notification (Discord, Telegram, email)
});

Always include error handling for provider disconnections and implement a restart mechanism.

For production systems, consider these critical enhancements: Filtering to listen only for proposals from specific DAOs or above a certain threshold. Idempotency to handle duplicate events that can occur during re-orgs by checking a processed event log. Resilience by using a process manager like PM2 to restart the script on crashes and logging all events to a database for audit trails. This transforms a simple script into a reliable service.

The event arguments you receive contain all relevant proposal data. For a ProposalCreated event, you get the proposal id, proposer address, targets (contracts to call), calldatas (function calls), and the description. You should parse the description, which is often a JSON string containing the proposal title and details. Extracting and formatting this data is key for creating informative alerts. For VoteCast events, you would capture the voter, proposal ID, and vote weight.

Once your listener is capturing events, the next step is to connect it to notification channels. The callback function is where you integrate with services like Discord Webhooks, the Telegram Bot API, or transactional email providers. Structure your alert to include the most actionable information: proposal ID, title, voting deadline, and a direct link to the governance forum or voting interface. This completes the core monitoring loop of your governance alert system.

The notification service backend is a Node.js application that acts as a relay between the blockchain and your users. Its primary function is to subscribe to events from the Indexer API you built in Step 2, process the data, and prepare formatted messages for various communication channels like email, Discord, or Telegram. You can structure this as a simple Express server or a serverless function, depending on your scalability needs.

Start by setting up a new project and installing essential dependencies. You will need ethers or viem to decode event logs, a database client like pg for PostgreSQL to store user preferences and sent notifications, and SDKs for your chosen notification platforms (e.g., nodemailer for email, discord.js for Discord webhooks). The core logic involves creating an endpoint that your indexer can POST new events to, or setting up a worker that periodically polls the indexer's database.

For each incoming governance event, the service must execute critical logic. First, it queries the database to find all users who are subscribed to alerts for the specific DAO, proposal type, or threshold (e.g., "notify me for all Snapshot votes on Uniswap"). Then, it applies user-defined filters; a user might only want alerts for proposals where the voting difference is less than 5%. Finally, it formats a human-readable message, injecting key data like proposal title, link, and current vote tally.

A robust implementation includes idempotency and deduplication to prevent spamming users. Store a hash (e.g., daoAddress-proposalId-eventType) of every processed alert in your database. Before sending any notification, check this table to ensure the same alert hasn't been sent recently. This is crucial for events that might be indexed multiple times or for state changes that trigger multiple similar events.

Here is a simplified code skeleton for the main alert processing function:

javascriptCopy
async function processGovernanceEvent(eventData) {
  // 1. Decode event with ethers/viem
  // 2. Query DB for subscribed users matching this event
  // 3. Apply user filters to the event data
  // 4. For each eligible user, format message
  // 5. Check deduplication table before sending
  // 6. Send via chosen channel (Email/Discord/Telegram)
  // 7. Record sent alert in deduplication table
}

Finally, consider monitoring and logging. Use a service like Sentry to catch errors in event decoding or message sending. Log key metrics: events received, notifications sent, and failures. This backend is now the operational core of your alert system, turning raw blockchain data into actionable, timely information for your users.

A Discord webhook is a simple HTTP endpoint that allows external applications to post messages directly to a designated channel. For governance monitoring, you can configure a webhook to receive alerts from your script or bot. To create one in Discord, navigate to your server's Channel Settings > Integrations > Webhooks, and click Create Webhook. Copy the generated Webhook URL—this is the address your code will send HTTP POST requests to. Keep this URL private, as anyone with it can send messages to your channel.

The core implementation involves sending a JSON payload to the webhook URL. Discord's API expects a specific structure. The most basic alert sends a plain text message. Here is a Python example using the requests library:

pythonCopy
import requests
WEBHOOK_URL = "your_discord_webhook_url_here"
def send_discord_alert(message):
    data = {"content": message}
    response = requests.post(WEBHOOK_URL, json=data)
    return response.status_code == 204

You would call this function with a string like "New Proposal #42 Created: Upgrade Treasury Contract" after your monitoring logic detects the on-chain event.

For more readable and structured alerts, use Discord Embeds. Embeds allow you to format messages with titles, descriptions, colors, and fields. This is ideal for presenting key proposal data concisely. An embed payload is more complex. Below is an example structure for a proposal alert:

pythonCopy
alert_embed = {
    "embeds": [{
        "title": "Proposal Created: #42",
        "description": "Upgrade to Treasury Contract v1.5",
        "color": 3447003, # Decimal color code (e.g., blue)
        "fields": [
            {"name": "Proposer", "value": "0xabc...123", "inline": True},
            {"name": "End Block", "value": "18945600", "inline": True}
        ]
    }]
}
requests.post(WEBHOOK_URL, json=alert_embed)

You can customize colors (green for passed votes, red for failed) and add fields for any relevant on-chain data.

To build a robust system, your governance monitoring script should catch exceptions from the webhook call. Network issues or an invalidated URL can cause failures. Implement retry logic with exponential backoff and logging. Furthermore, consider rate limits; Discord allows approximately 30 requests per minute per channel. If you are monitoring many events across multiple protocols, you may need to batch alerts or implement a message queue to stay within this limit. Always test your webhook with a dedicated test channel before connecting it to a main community channel.

In practice, you will integrate this webhook call into the event listener or polling loop from the previous steps. For instance, upon detecting a new ProposalCreated event from a Compound Governor contract, your script would fetch the proposal details, format them into an embed, and dispatch them via the send_discord_alert function. This creates a closed loop: on-chain activity triggers an off-chain notification, keeping your community informed in real time without manual intervention.

A governance system is only as effective as its participation rate. To combat voter apathy and ensure timely responses, you need to implement automated alerts. This step involves connecting your on-chain governance contract to off-chain notification services. We'll use a serverless function or a dedicated bot to monitor blockchain events—like new proposals (ProposalCreated), voting periods opening/closing, and final execution—and then trigger notifications. This moves governance from a passive, check-the-dashboard model to an active, push-based system that drives engagement.

For Twitter (X) notifications, you'll typically use the platform's API v2. After creating a developer account and a project, you generate the necessary API keys and access tokens. Your monitoring script will use a library like tweepy for Python or twitter-api-v2 for Node.js to post updates. A tweet for a new proposal should include the proposal ID, a brief title, the voting start/end blocks, and a link to the governance interface. Remember to adhere to Twitter's automation rules and avoid spammy behavior to prevent account suspension.

Email notifications require an SMTP service provider. Services like SendGrid, Mailgun, or Amazon SES are reliable choices for transactional emails. Your script will format an HTML or plain-text email containing the critical governance event details. For each event type, define a template: a new proposal email might have the subject "New Governance Proposal #12: Treasury Allocation" and include the proposer's address, proposal description, and voting timeline. Ensure you handle email unsubscribes and comply with anti-spam regulations like CAN-SPAM or GDPR by including an unsubscribe link in every message.

The core logic resides in an event listener. Using a provider like Alchemy or Infura with WebSocket connections, you can listen for your contract's events in real-time without polling. Here's a simplified Node.js snippet using ethers.js and the @sendgrid/mail library:

javascriptCopy
const filter = contract.filters.ProposalCreated();
contract.on(filter, (proposalId, proposer, targets, values, signatures, calldatas, startBlock, endBlock, description) => {
  // 1. Format message
  const tweet = `New Proposal #${proposalId}: "${description.substring(0, 50)}..."\nVoting: Blocks ${startBlock}-${endBlock}\n${GOVERNANCE_UI_LINK}`;
  // 2. Post to Twitter
  await twitterClient.v2.tweet(tweet);
  // 3. Send Email
  const msg = { to: SUBSCRIBERS_LIST, from: 'governance@dao.org', subject: `New Proposal #${proposalId}`, html: generateProposalEmailHTML(...) };
  await sgMail.send(msg);
});

This listener triggers both notification channels simultaneously upon detecting the on-chain event.

Before going live, implement critical safeguards. Use a dedicated, secure environment variable manager for all API keys and secrets. Add rate limiting to your Twitter client and email sender to avoid hitting service quotas. Establish a failure-handling routine with retry logic and dead-letter queues—if Twitter's API is down, log the error and retry twice before alerting an admin. Finally, provide a clear way for users to manage their notification preferences, such as a simple web form to opt-in or out of specific alert types, ensuring the system respects user choice and maintains trust.

Governance participation depends on timely information. An automated alert system ensures stakeholders are notified about new proposals, voting deadlines, and execution events without manual monitoring. For DAOs like Uniswap or Compound, missing a critical vote can stall protocol upgrades or treasury management. Setting up notifications involves three core components: an event listener (indexer), a notification logic layer, and delivery channels like email, Discord, or Telegram. This automation transforms passive governance into an active, responsive process.

The technical foundation is an indexer that listens for on-chain events. You can use a service like The Graph to create a subgraph for your governance contract, tracking events such as ProposalCreated, VoteCast, and ProposalExecuted. Alternatively, run a custom listener using ethers.js or viem. For example, a script can poll an RPC provider for new logs from the governor contract's ProposalCreated event. The key is to capture the proposal ID, description, start/end blocks, and proposer address for further processing.

Once an event is captured, the logic layer determines who needs to be notified and formats the message. This often involves querying the governance contract for details like the current vote tally or quorum status. For token-weighted voting systems, you might calculate participation rates. The logic should also filter for importance; you may only want alerts for proposals that pass a certain threshold of delegated votes or involve treasury transactions above a specific amount. This logic is typically implemented in a serverless function (AWS Lambda, Vercel Edge Function) or a dedicated microservice.

Notification delivery integrates with common communication platforms. For Discord, use webhooks to post formatted messages to a dedicated governance channel. For Telegram, utilize the Bot API. Email alerts can be sent via services like SendGrid or Resend, potentially targeting delegates based on their voting power. A robust system includes fallback channels and rate limiting to avoid spam. Here's a simplified Node.js snippet using ethers and a Discord webhook:

javascriptCopy
// Pseudo-code for a Discord alert
const { WebhookClient } = require('discord.js');
const webhook = new WebhookClient({ url: process.env.DISCORD_WEBHOOK_URL });

async function sendProposalAlert(proposalId, description) {
  await webhook.send({
    content: `New Proposal #${proposalId}\n**${description}**\nVoting starts soon.`
  });
}

Maintenance involves monitoring the health of the alert system itself. Log successful sends and failures, and set up alerts for when the indexer falls behind or the RPC connection fails. Regularly update the system to accommodate governance contract upgrades or changes in the notification platform APIs. For multi-chain DAOs, ensure the system supports all relevant networks (Ethereum Mainnet, Arbitrum, Polygon). The end goal is a reliable pipeline that increases governance participation by reducing information asymmetry and administrative overhead for all members.

This guide walked through the essential components of a governance notification system: setting up a data source like a subgraph or RPC provider, writing a monitoring script using ethers.js or viem, and integrating with a notification service such as Discord Webhooks or Telegram Bots. The core logic involves polling for new events from a governor contract's ProposalCreated function and filtering for proposals that meet your criteria, such as a minimum quorum or specific target contracts.

For production use, consider these enhancements to improve reliability and coverage. Implement error handling and retry logic for RPC calls. Use a database to track processed proposals and prevent duplicate alerts. Expand monitoring to include proposal state changes (e.g., ProposalQueued, ProposalExecuted) and vote casting events to track community sentiment in real-time. For multi-chain DAOs, you will need to run parallel monitors for each chain where governance is active.

The next step is to explore more advanced data sources. While subgraphs are convenient, they can have indexing delays. For near real-time alerts, consider using Chainscore's real-time event streaming API, which provides low-latency access to contract events across multiple chains without managing infrastructure. Alternatively, tools like OpenZeppelin Defender offer managed automation and sentinel services specifically for governance and admin actions.

To deepen your understanding, review the Governor contract standards (OpenZeppelin Governor, Compound's Bravo) to understand all emitted events and state transitions. Practice by forking a mainnet DAO like Uniswap or Aave on a testnet and deploying your monitor against it. Finally, share your setup with the community; many DAOs have public Discord channels dedicated to governance tools and bots where you can contribute your work.