[![Build Status](https://travis-ci.org/poanetwork/poa-governance-notifications.svg?branch=master)](https://travis-ci.org/poanetwork/poa-governance-notifications) # `poa-governance-notifications` A CLI tool for monitoring a blockchain for POA Network governance ballots. This tool can be used to monitor _any_ chain that uses POA Network's governance contracts. More info regarding governance can be found in [POA Network's Wiki](https://github.com/poanetwork/wiki/wiki/Governance-Overview). POA Network's governance contracts can be found in the [`poa-network-consensus-contracts` repo](https://github.com/poanetwork/poa-network-consensus-contracts/tree/master/contracts), all Solidity files prefixed with "Voting" are classified as a "governance contract". The `poagov` command line tool is distributed as a binary for Linux and OSX. The `poagov` binary can be built from source for both OSX and Linux using the code in this repo. ### Downloading the `poagov` Binary *Note:* the `poagov` binary requires `libssl` to be installed prior to usage, if you do not have `libssl` installed, go to the "Requires libssl" section in this README to find out how to download it. # Download `poagov` for Debian/Ubuntu: $ curl -OL https://github.com/poanetwork/poa-governance-notifications/releases/download/v2.0.0/poagov-2.0.0-linux-x86_64.tar.gz $ tar -xvzf poagov-2.0.0-linux-x86_64.tar.gz $ rm poagov-2.0.0-linux-x86_64.tar.gz $ cd poa-governance-notifications $ mv sample.env .env # Optionally rename binary from `poagov-2.0.0-linux-x86_64` to `poagov`: $ mv poagov-2.0.0-linux-x86_64 poagov # Or download `poagov` for OSX: $ curl -OL https://github.com/poanetwork/poa-governance-notifications/releases/download/v2.0.0/poagov-2.0.0-osx-x86_64.tar.gz $ tar -xvzf poagov-2.0.0-osx-x86_64.tar.gz $ rm poagov-2.0.0-osx-x86_64.tar.gz $ cd poa-governance-notifications $ mv sample.env .env # Optionally rename binary from `poagov-2.0.0-osx-x86_64` to `poagov`: $ mv poagov-2.0.0-osx-x86_64 poagov # If you did not rename your binary in the previous step, replace "poagov" # in the following commands with your Linux or OSX binary's name: $ chmod +x poagov $ ./poagov --help ### Building `poagov` from Source To build the `poagov` CLI tool from source, clone this repo and run: $ cargo build --release `poagov` can be built with Rust 1.31.0-stable or later and requires `libssl`; see the "Running and Building `poagov` Requires `libssl`" section in this README for more information. ##### Testing `poagov` You can run `poagov`'s tests to ensure that everything is working properly: $ cargo test --release ### Running and Building `poagov` Requires `libssl` SMTP over TLS requires that you have a native TLS library installed on your machine, the preferred library for Linux and OSX is OpenSSL >= 1.0.1, otherwise known as `libssl`. If running `cargo build --release` panics with an error like: "error: failed to run custom build command for `openssl-sys v0.9.28 ... Could not find directory of OpenSSL installation ..." you probably do not have `libssl` installed. You can use `dpkg` to check to see if you have `libssl` installed, and if so which version(s) are installed: $ dpkg -l | grep libssl To install `libssl` on Debian/Ubuntu run the following: $ sudo apt update $ sudo apt-get install -y pkg-config libssl-dev To install `libssl` on MacOS run the following: $ brew update $ brew install openssl Then try to rebuild `poagov` using: $ cargo clean $ cargo build --release If you are on OSX and installed OpenSSL using Homebrew and continue to get compilation errors for any of the Rust crates: `openssl`, `openssl-sys`, or `openssl-sys-extras`, try building with the following: $ cargo clean $ OPENSSL_INCLUDE_DIR=$(brew --prefix openssl)/include \ OPENSSL_LIB_DIR=$(brew --prefix openssl)/lib \ cargo build --release There is a known issue regarding the `openssl-sys` crate not being able to find `libssl` installed with Homebrew on OSX; more information can be found on [Stack Overflow](https://stackoverflow.com/questions/34612395/openssl-crate-fails-compilation-on-mac-os-x-10-11/34615626#34615626). The above solution comes from the linked Stack Overflow thread. More information on common issues encountered while installing the `openssl` Rust crate can be found [here](https://crates.io/crates/openssl). ### Usage Once you have built or downloaded `poagov`, you can print out the CLI usage by running: # If you downloaded the `poagov` binary run: $ poagov --help # Or, if you built `poagov` from source run: $ target/release/poagov --help poagov 2.0.0 Monitors a POA Network blockchain for governance events. USAGE: poagov [FLAGS] [OPTIONS] FLAGS: --core Monitors POA Network's Core Network for governance ballots --sokol Monitors POA Network's Sokol network for governance ballots --xdai Monitors the xDai Network for governance ballots --v1 Monitors the v1 governance contracts --v2 [default] Monitors the v2 governance contracts, if no contract version CLI argument is given by -k, --keys Monitors the blockchain for ballots to change keys -t, --threshold Monitors the blockchain for ballots to change the minimum threshold the user, we set this CLI flag -p, --proxy Monitors the blockchain for ballots to change the proxy address -e, --emission Monitors the blockchain for ballots to manage emission funds --earliest Monitor for governance events starting at the blockchain's first block --latest Monitor for governance events starting at the blockchain's most recently mined block --email Enables email notifications (SMTP configuration options must be set in your `.env` file) --log-emails Logs the full email body for each notification generated, this option does not require the `--email` flag to be set --log-file Logs are written to files in the ./logs directory, logs are rotated chronologically across 3 files, each file has a max size of 4MB -h, --help Prints help information -V, --version Prints version information OPTIONS: --block-time The average number of seconds it takes to mine a new block -n, --limit Stops `poagov` after this many notifications have been generated (this option can be useful when testing `poagov`) --start Start monitoring for governance events at this block (inclusive) --tail Start monitoring for governance events for the `n` blocks prior to the last mined block Hitting `[ctrl-c]` while `poagov` is running will cause the process to gracefully shutdown. ##### Required CLI Arguments Each time you run `poagov`, three CLI arguments are required: 1. The chain (specify only one): `--core`, `--sokol`, `--xdai`. 2. The governance ballots to monitor (specify at least one): `--keys`, `--threshold`, `--proxy`, `--emission`. 3. The block in the chain from where to start monitoring (specify only one): `--earliest`, `--latest`, `--start=`, `--tail=`. ##### Notes on the Hardfork Version CLI Options: `--v1` and `--v2` `--v1` indicates that you want to monitor for governance events prior to the Sokol and Core hardforks that will occur in September-2018 and November-2018 respectively. `--v2` indicates that you want to monitor for governance events that occurred after the above hardfork dates. We default to `--v2` being set as it will monitor the currently deployed contract. - More information regarding the planned hardforks for the POA Sokol and Core chains in September and November 2018 can be found [here](https://medium.com/poa-network/poa-network-news-and-updates-36-2e6e00550c15). ### Optional Arguments Providing the `--v1` flag will tell `poagov` to look for ballots corresponding to the hardfork #1 governance contracts. The hardfork #1 contracts are not currently being by POA Network and not new governance notifications will be generated, however you can use `poagov` to view all past `--v1` ballots that have occurred using: $ poagov <--core, --sokol> --v1 --earliest -ktp Providing the `--email` flag will enable governance notification via email. To use this option, you must first configure SMTP in your `.env` file. Providing the `--block-time=` will set how often `poagov` will query the blockchain for new governance events. Defaults to 30 seconds. Providing the `--log-emails` flag will print the full text for a notification email to `stderr` when governance events are found. When this option is set, email text will be logged regardless of whether or not the `--email` flag is set. Setting the `--log-file` flag will write logs to a file in the `logs/` directory. Logs are rotated chronologically across three files. Once the `logs/` directory has reached its max number of files, the oldest log file will be deleted to make room for the next log file. Log files have a max size of 4MB; the log files will rotated once the current log file has reached the max file size. Setting the `--limit=` option will cause `poagov` to stop once `value` number of notifications have been generated. This option is useful when testing. ### Setting up the `.env` File When the `poagov` CLI tool is run, the process' environment variables are loaded via an `.env` file. The `.env` file contains configuration variables that are not specified via the command line. You are required to have an `.env` file in the same directory as your `Cargo.toml` or `poagov` binary. If you downloaded a `.tar.gz` compressed archive containing the `poagov` binary and you do not have an `.env` file in the unarchived directory, manually copy the `sample.env` file in this repo into a file called `.env` in the same directory as the `poagov` binary. When building from source, the `sample.env` file will be copied into the `.env` file. The default `.env` file will contain the default configuration values required to run `poagov`. If you wish to enable email notifications, you must add the required SMTP config values to your `.env` file. See the "Setting up Email Notifications" section for details. ##### Setting up Email Notifications In order to enable email notifications, you must change the name of the `sample.env` file to `.env`. Then, you must add values for the following SMTP config options in your `.env` file: SMTP_HOST_DOMAIN= SMTP_PORT= SMTP_USERNAME= SMTP_PASSWORD= OUTGOING_EMAIL_ADDRESS= EMAIL_RECIPIENTS= Add a comma-separated list of email address to the `EMAIL_RECIPIENTS` config option in your `.env` file. These addresses will be sent emails when `poagov` encounters new ballots. *Note* `poagov` forces SMTP email notifcations to be sent over TLS/STARTTLS, if your SMTP Host does not support TLS or STARTTLS, `poagov` will `panic!`. You may notice that we default `SMTP_PORT` to port 587 for STARTTLS, but you may use any port for which your outgoing email server is listening; port 465 is commonly used for TLS. Your SMTP configuration should look something like the following: SMTP_HOST_DOMAIN=mail.riseup.net SMTP_PORT=587 SMTP_USERNAME=evariste_galois SMTP_PASSWORD='finteFIELDS#$!' OUTGOING_EMAIL_ADDRESS=evariste_galois@riseup.net EMAIL_RECIPIENTS=alice@poa.network,bob@poa.network ### An Explained Example $ poagov --sokol --v1 -kt --earliest --email --log-emails --limit=1 - `--sokol` monitors the Sokol chain. - `--v1` monitors the governance contracts deployed prior to September-2018. - `-k` monitors the `VotingToChangeKeys` contract. - `-t` monitors the `VotingToChangeMinThreshold` contract. - `--earliest` start monitoring from the first block in the blockchain. - `--email` sends out email notifications to each address in the `EMAIL_RECIPIENTS` env-var. - `--log-emails` for each governance notification generated, log the corresponding email body. - `--limit=1` stop running `poagov` after one ballot notification has been generated. ### Logs Logs are written to `stderr` by default; if the `--log-file` CLI flag is set, then logs will be written to a file in the `logs.` directory. Logged information includes: the generation of governance notifications, sending an email successfully, failing to send an email, blocks that we have finished monitoring, email bodies generated (using the `--log-emails` CLI option). The following is an example command with its corresponding logs: $ poagov --sokol --v1 --threshold --earliest --limit=3 Oct 10 15:18:09.863 INFO starting poagov... Oct 10 15:18:10.287 INFO governance notification, block_number: 525296, ballot_id: 0, ballot: Threshold Oct 10 15:18:10.287 INFO governance notification, block_number: 599789, ballot_id: 1, ballot: Threshold Oct 10 15:18:10.287 INFO governance notification, block_number: 1078816, ballot_id: 2, ballot: Threshold Oct 10 15:18:10.287 WARN reached notification limit, gracefully shutting down..., limit: 3